@llblab/pi-telegram 0.51.5 → 0.52.0

package/dist/lib/telegram-api.js

@@ -7,13 +7,13 @@
  */
 import { randomUUID } from "node:crypto";
 import { createWriteStream, openAsBlob } from "node:fs";
-import { mkdir, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { request as requestHttps } from "node:https";
 import { join } from "node:path";
-import { resolveTelegramTempDir } from "./paths.js";
+import { resolveTelegramAttachmentsDir } from "./paths.js";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
-export const TELEGRAM_API_BASE = "https://api.telegram.org";
+const TELEGRAM_API_BASE = "https://api.telegram.org";
 export const TELEGRAM_FILE_MAX_BYTES = 50 * 1024 * 1024;
 export function getTelegramInboundFileByteLimitFromEnv(env, names, defaultValue = TELEGRAM_FILE_MAX_BYTES) {
     for (const name of names) {
@@ -27,11 +27,10 @@ export function getTelegramInboundFileByteLimitFromEnv(env, names, defaultValue
     return defaultValue;
 }
 function getTelegramApiTempDir() {
-    return resolveTelegramTempDir();
+    return resolveTelegramAttachmentsDir();
 }
 const TELEGRAM_TEMP_FILE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const activeTelegramApiWorkspaceAdmissionOperationIds = new Set();
-const TELEGRAM_TEMP_SCRATCH_FILE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-/u;
 const TELEGRAM_INBOUND_FILE_MAX_BYTES = getTelegramInboundFileByteLimitFromEnv(process.env, ["PI_TELEGRAM_INBOUND_FILE_MAX_BYTES", "TELEGRAM_MAX_FILE_SIZE_BYTES"], TELEGRAM_FILE_MAX_BYTES);
 const TELEGRAM_NETWORK_FAMILY_ENV = "PI_TELEGRAM_NETWORK_FAMILY";
 const TELEGRAM_NETWORK_FAMILY_VALUES = new Set([
@@ -208,6 +207,23 @@ export function createTelegramApiWorkspaceAdmissionClient(client, admission, opt
 function sanitizeFileName(name) {
     return name.replace(/[^a-zA-Z0-9._-]+/g, "_");
 }
+/** Names follow `<kind>-<scope>-<messageId>[-<index>][-<name>|.<ext>]`. */
+/**
+ * `scope` is the bot `@username` (id fallback) in a private chat and the public chat `@username` (id fallback) elsewhere.
+ * A negative chat id loses its sign, so the name never contains two adjacent dashes.
+ */
+export function createTelegramAttachmentFileName(source, generatedName, botScope) {
+    const chat = source.chat;
+    const clean = (value) => sanitizeFileName(value.replace(/^@/u, "")).replace(/^[-.]+/u, "");
+    const scope = source.scope ? clean(source.scope) : chat?.type === "private" || !chat
+        ? botScope ? clean(botScope) : chat ? String(Math.abs(chat.id)) : ""
+        : chat.username ? clean(chat.username) : String(Math.abs(chat.id));
+    const dot = generatedName.lastIndexOf(".");
+    const extension = dot > 0 ? sanitizeFileName(generatedName.slice(dot)) : "";
+    const tail = source.userFileName ? `-${clean(source.userFileName)}` : extension;
+    return [sanitizeFileName(source.kind), scope, String(source.messageId)].filter(Boolean).join("-") +
+        (source.index !== undefined ? `-${source.index}` : "") + tail;
+}
 class TelegramApiMalformedSuccessError extends Error {
     constructor(method, detail) {
         super(`Telegram API ${method} ${detail}`);
@@ -672,9 +688,9 @@ export async function cleanupTelegramTempFiles(tempDir, maxAgeMs, now = Date.now
         return 0;
     }
     for (const entry of entries) {
-        if (!entry.isFile() || !TELEGRAM_TEMP_SCRATCH_FILE_PATTERN.test(entry.name)) {
+        // The directory holds only attachment scratch files, so age alone decides.
+        if (!entry.isFile())
             continue;
-        }
         const path = join(tempDir, entry.name);
         try {
             const stats = await stat(path);
@@ -760,7 +776,9 @@ export async function downloadTelegramFile(botToken, fileId, suggestedName, temp
     const file = await callTelegram(configuredBotToken, "getFile", { file_id: fileId }, { signal: options?.signal });
     assertTelegramFileSizeWithinLimit(file.file_size, options?.maxFileSizeBytes);
     await mkdir(tempDir, { recursive: true, mode: 0o700 });
-    const targetPath = join(tempDir, `${randomUUID()}-${sanitizeFileName(suggestedName)}`);
+    // Names carry scope and message id, so the same message maps to the same path; publish by rename.
+    const targetPath = join(tempDir, sanitizeFileName(suggestedName));
+    const partPath = `${targetPath}.${randomUUID()}.part`;
     const response = await callTelegramTransportRequest((family) => telegramFetch(`${TELEGRAM_API_BASE}/file/bot${configuredBotToken}/${file.file_path}`, { signal: options?.signal }, family));
     if (!response.ok) {
         throw new Error(`Failed to download Telegram file: ${response.status}`);
@@ -768,10 +786,11 @@ export async function downloadTelegramFile(botToken, fileId, suggestedName, temp
     const contentLength = response.headers?.get("content-length");
     assertTelegramFileSizeWithinLimit(contentLength ? Number.parseInt(contentLength, 10) : undefined, options?.maxFileSizeBytes);
     try {
-        await writeTelegramDownloadResponse(response, targetPath, options?.maxFileSizeBytes);
+        await writeTelegramDownloadResponse(response, partPath, options?.maxFileSizeBytes);
+        await rename(partPath, targetPath);
     }
     catch (error) {
-        await removeTelegramPartialDownload(targetPath);
+        await removeTelegramPartialDownload(partPath);
         throw error;
     }
     return targetPath;
@@ -788,17 +807,6 @@ export async function answerTelegramCallbackQuery(botToken, callbackQueryId, tex
         }));
     }
 }
-export async function deleteTelegramMessage(botToken, chatId, messageId) {
-    try {
-        await callTelegram(botToken, "deleteMessage", {
-            chat_id: chatId,
-            message_id: messageId,
-        });
-    }
-    catch {
-        // ignore
-    }
-}
 export function createTelegramChatActionSender(sendChatAction, action) {
     return (chatId, options) => sendChatAction(chatId, action, options);
 }
@@ -871,6 +879,7 @@ export function createDefaultTelegramBridgeApiRuntime(deps) {
         tempDir: getTelegramApiTempDir(),
         maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
         tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
+        ...(deps.getBotScope ? { getBotScope: deps.getBotScope } : {}),
         recordRuntimeEvent: deps.recordRuntimeEvent,
         captureRequestErrorHandler: deps.captureRequestErrorHandler,
     });
@@ -1029,9 +1038,11 @@ export function createTelegramBridgeApiRuntime(deps) {
          * Downloads a file from the Telegram servers into the local temp directory.
          * Used for inbound voice messages, photos, documents, etc.
          */
-        downloadFile: async (fileId, suggestedName) => {
+        downloadFile: async (fileId, suggestedName, source) => {
             try {
-                return await deps.client.downloadFile(fileId, suggestedName, deps.tempDir, {
+                return await deps.client.downloadFile(fileId, source
+                    ? createTelegramAttachmentFileName(source, suggestedName, deps.getBotScope?.())
+                    : suggestedName, deps.tempDir, {
                     maxFileSizeBytes: deps.maxFileSizeBytes,
                 });
             }

package/dist/lib/thread-cleanup-manager.d.ts

@@ -173,6 +173,7 @@ export interface TelegramThreadCleanupWorkStore {
 }
 export declare function createTelegramThreadCleanupWorkStore(options: {
     path: string;
+    runtimeDir?: string;
     profileName: string;
     tokenSha256: string;
     maxWorkSets?: number;

package/dist/lib/thread-cleanup-manager.js

@@ -7,6 +7,8 @@ import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openS
 import { dirname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { renameTelegramPathWithRetry, withTelegramFileTransaction } from "./locks.js";
+import { getTelegramJournalPublicationPaths } from "./paths.js";
+import { isWireRecord as isObject, hasOnlyWireKeys as onlyKeys, isNonNegativeWireInteger as safeTime, } from "./wire.js";
 function targetKey(target) {
     return `${target.chatId}:${target.threadId}`;
 }
@@ -134,16 +136,6 @@ export function createTelegramInactiveThreadCleanupReviewRuntime(deps) {
         },
     };
 }
-function isObject(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
-function onlyKeys(value, keys) {
-    const allowed = new Set(keys);
-    return Object.keys(value).every(key => allowed.has(key));
-}
-function safeTime(value) {
-    return Number.isSafeInteger(value) && value >= 0;
-}
 function validateWorkSet(value, profileName) {
     if (!isObject(value) || !onlyKeys(value, ["operationId", "createdAtMs", "entries"]) ||
         typeof value.operationId !== "string" || !value.operationId || !safeTime(value.createdAtMs) ||
@@ -199,7 +191,18 @@ function validateWorkSet(value, profileName) {
 function sameCandidates(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
 }
+function parseTelegramThreadCleanupWorkFile(value, profileName, tokenSha256) {
+    if (!isObject(value) || !onlyKeys(value, ["version", "profileName", "tokenSha256", "workSets"]) ||
+        value.version !== 1 || value.profileName !== profileName || value.tokenSha256 !== tokenSha256 || !Array.isArray(value.workSets))
+        throw new Error("Telegram Thread cleanup store identity or schema does not match.");
+    const workSets = value.workSets.map(workSet => validateWorkSet(workSet, profileName));
+    if (new Set(workSets.map(workSet => workSet.operationId)).size !== workSets.length)
+        throw new Error("Telegram Thread cleanup operation identity is ambiguous.");
+    return { version: 1, profileName, tokenSha256, workSets };
+}
 export function createTelegramThreadCleanupWorkStore(options) {
+    options = { ...options };
+    const publicationPaths = getTelegramJournalPublicationPaths(options.path, options.runtimeDir);
     const maxWorkSets = options.maxWorkSets ?? 32;
     const maxBytes = options.maxBytes ?? 1024 * 1024;
     const now = options.getNowMs ?? Date.now;
@@ -236,14 +239,7 @@ export function createTelegramThreadCleanupWorkStore(options) {
         finally {
             closeSync(fd);
         }
-        if (!isObject(value) || !onlyKeys(value, ["version", "profileName", "tokenSha256", "workSets"]) ||
-            value.version !== 1 || value.profileName !== options.profileName ||
-            value.tokenSha256 !== options.tokenSha256 || !Array.isArray(value.workSets))
-            throw new Error("Telegram Thread cleanup store identity or schema does not match.");
-        const workSets = value.workSets.map(workSet => validateWorkSet(workSet, options.profileName));
-        if (new Set(workSets.map(workSet => workSet.operationId)).size !== workSets.length)
-            throw new Error("Telegram Thread cleanup operation identity is ambiguous.");
-        return { version: 1, profileName: options.profileName, tokenSha256: options.tokenSha256, workSets };
+        return parseTelegramThreadCleanupWorkFile(value, options.profileName, options.tokenSha256);
     };
     const publish = (file) => {
         if (file.workSets.length > maxWorkSets)
@@ -251,8 +247,9 @@ export function createTelegramThreadCleanupWorkStore(options) {
         const serialized = `${JSON.stringify(file, null, 2)}\n`;
         if (Buffer.byteLength(serialized) > maxBytes)
             throw new Error("Telegram Thread cleanup byte capacity reached.");
-        const temporaryPath = `${options.path}.${process.pid}.${randomUUID()}.tmp`;
+        const temporaryPath = `${publicationPaths.temporaryBasePath}.${process.pid}.${randomUUID()}.tmp`;
         mkdirSync(dirname(options.path), { recursive: true, mode: 0o700 });
+        mkdirSync(dirname(temporaryPath), { recursive: true, mode: 0o700 });
         try {
             writeFileSync(temporaryPath, serialized, { mode: 0o600 });
             chmodSync(temporaryPath, 0o600);
@@ -269,7 +266,7 @@ export function createTelegramThreadCleanupWorkStore(options) {
             catch { /* rename consumed it */ }
         }
     };
-    const mutate = (operation) => withTelegramFileTransaction(`${options.path}.transaction`, () => operation(read()));
+    const mutate = (operation) => withTelegramFileTransaction(publicationPaths.transactionPath, () => operation(read()));
     return {
         prepare(operationId, candidates) {
             if (!operationId || candidates.length === 0 || candidates.some(candidate => candidate.profileName !== options.profileName))
@@ -343,7 +340,7 @@ export function createTelegramThreadCleanupWorkStore(options) {
             });
         },
         list() {
-            return structuredClone(withTelegramFileTransaction(`${options.path}.transaction`, () => read().workSets));
+            return structuredClone(withTelegramFileTransaction(publicationPaths.transactionPath, () => read().workSets));
         },
     };
 }

package/dist/lib/thread-naming.d.ts

@@ -1,10 +1,10 @@
 /**
- * Telegram Thread manual-name dialog state
- * Zones: telegram, thread identity, runtime controls
- * Owns one expiring exact-target interaction per session scope.
- * Excludes Telegram transport, durable Workspace mutation, and name validation.
+ * Telegram Thread naming rules and manual-name interaction
+ * Zones: thread identity names, palettes, title formatting, runtime controls
+ * Owns name/title value policy and one expiring exact-target dialog per session scope.
+ * Excludes occupancy/slot allocation, display-mode projection, transport and API/store effects.
  */
-import type { TelegramTarget } from "./target.ts";
+import { type TelegramTarget } from "./target.ts";
 export declare const TELEGRAM_THREAD_NAME_DIALOG_TTL_MS: number;
 export type TelegramThreadNameDialogAction = "reset" | "cancel";
 export interface TelegramThreadNameDialogCandidate {
@@ -44,3 +44,30 @@ export declare function createTelegramThreadNameDialogRuntime(options?: {
     clearScope(scope: string): void;
     inspect(target: TelegramTarget): TelegramThreadNameDialogCandidate | undefined;
 };
+export interface TelegramThreadTitleInput {
+    instanceId: string;
+    profileKey: string;
+    threadName?: string;
+}
+export interface TelegramThreadNameInput {
+    seed: string;
+    cwd?: string;
+    role?: "leader" | "follower";
+    peers?: readonly string[];
+    slot?: string;
+}
+export declare function createTelegramThreadName(input: TelegramThreadNameInput): string;
+export declare function normalizeTelegramTopicTargetThreadName(threadName: string): string;
+export declare function getTelegramTopicIdentityName(threadName: string): string;
+export declare function chooseTelegramThreadName(input: {
+    slot: string | undefined;
+    entropy?: number | string;
+    getRandom?: () => number;
+    occupied?: readonly string[];
+}): string | undefined;
+export declare function getTelegramThreadNameLeadingSlot(threadName: string | undefined): string | undefined;
+export declare function getTelegramTopicThreadNameValidationError(threadName: string, _slot: string | undefined): string | undefined;
+export declare function getTelegramManualThreadDisplayNameValidationError(threadName: string): string | undefined;
+export declare function isTelegramTopicThreadNameValidForSlot(threadName: string, slot: string | undefined): boolean;
+export declare function getTelegramTopicName(request: TelegramThreadTitleInput, template?: string, slot?: string): string;
+export declare function getTelegramTopicTitleForThreadName(threadName: string, slot: string, template?: string): string;

package/dist/lib/thread-naming.js

@@ -1,16 +1,14 @@
 /**
- * Telegram Thread manual-name dialog state
- * Zones: telegram, thread identity, runtime controls
- * Owns one expiring exact-target interaction per session scope.
- * Excludes Telegram transport, durable Workspace mutation, and name validation.
+ * Telegram Thread naming rules and manual-name interaction
+ * Zones: thread identity names, palettes, title formatting, runtime controls
+ * Owns name/title value policy and one expiring exact-target dialog per session scope.
+ * Excludes occupancy/slot allocation, display-mode projection, transport and API/store effects.
  */
+import { areTelegramTargetsEqual as sameTarget } from "./target.js";
 export const TELEGRAM_THREAD_NAME_DIALOG_TTL_MS = 5 * 60_000;
 function targetKey(target) {
     return `${target.chatId}:${target.threadId ?? "chat"}`;
 }
-function sameTarget(left, right) {
-    return left.chatId === right.chatId && left.threadId === right.threadId;
-}
 function cloneCandidate(candidate) {
     return { ...candidate, target: { ...candidate.target } };
 }
@@ -76,3 +74,189 @@ export function createTelegramThreadNameDialogRuntime(options) {
         },
     };
 }
+function hashString(value) {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}
+function getWorkspaceHint(cwd) {
+    if (!cwd)
+        return undefined;
+    const parts = cwd.split("/").filter(Boolean);
+    const last = parts.at(-1)?.trim();
+    if (!last)
+        return undefined;
+    return (last
+        .replace(/[^\p{L}\p{N}._-]+/gu, " ")
+        .trim()
+        .slice(0, 32) || undefined);
+}
+export function createTelegramThreadName(input) {
+    const workspace = getWorkspaceHint(input.cwd);
+    const roleMark = input.role === "leader"
+        ? "Leader"
+        : input.role === "follower"
+            ? "Follower"
+            : undefined;
+    const slot = input.slot ? `Thread ${input.slot}` : undefined;
+    const peerSalt = input.peers?.slice().sort().join("|") ?? "";
+    const fallback = `Instance ${hashString(`${input.seed}|${input.cwd ?? ""}|${input.role ?? ""}|${peerSalt}|${input.slot ?? ""}`)
+        .toString(36)
+        .slice(0, 4)}`;
+    return ([slot, workspace, roleMark].filter(Boolean).join(" ").slice(0, 96) ||
+        fallback);
+}
+export function normalizeTelegramTopicTargetThreadName(threadName) {
+    return threadName.replace(/\s+/g, " ").trim().slice(0, 96);
+}
+function getGraphemeSegments(value) {
+    const segmenter = Intl.Segmenter;
+    if (!segmenter)
+        return Array.from(value);
+    return Array.from(new segmenter(undefined, { granularity: "grapheme" }).segment(value), (part) => part.segment);
+}
+export function getTelegramTopicIdentityName(threadName) {
+    return getGraphemeSegments(normalizeTelegramTopicTargetThreadName(threadName))
+        .join("")
+        .trim();
+}
+const TELEGRAM_THREAD_NAME_PALETTE = {
+    A: ["Atlas", "Aster", "Aurora", "Anchor", "Ashen"],
+    B: ["Beacon", "Briar", "Boreal", "Birch", "Bison"],
+    C: ["Cedar", "Comet", "Cipher", "Coral", "Cinder"],
+    D: ["Delta", "Dawn", "Drift", "Dune", "Dagger"],
+    E: ["Ember", "Echo", "Eagle", "Eden", "Elder"],
+    F: ["Falcon", "Fjord", "Flint", "Forest", "Fable"],
+    G: ["Grove", "Glade", "Glyph", "Garnet", "Gale"],
+    H: ["Harbor", "Hawk", "Hazel", "Helix", "Haven"],
+    I: ["Iris", "Ivory", "Iron", "Isle", "Idea"],
+    J: ["Jade", "Juno", "Jolt", "Jewel", "Jasper"],
+    K: ["Kite", "Karma", "Kernel", "Kodiak", "Kelp"],
+    L: ["Lumen", "Laurel", "Lynx", "Lotus", "Lagoon"],
+    M: ["Maple", "Meteor", "Meadow", "Marble", "Moss"],
+    N: ["Nimbus", "Nova", "Nectar", "North", "Noble"],
+    O: ["Orion", "Onyx", "Opal", "Orbit", "Olive"],
+    P: ["Pine", "Pulse", "Praxis", "Pebble", "Prism"],
+    Q: ["Quartz", "Quill", "Quasar", "Quest", "Quiver"],
+    R: ["River", "Raven", "Rune", "Reef", "Ridge"],
+    S: ["Spruce", "Solar", "Signal", "Stone", "Sable"],
+    T: ["Timber", "Talon", "Terra", "Torch", "Tide"],
+    U: ["Umber", "Unity", "Ursa", "Uplink", "Ulmus"],
+    V: ["Violet", "Vector", "Vista", "Vale", "Vortex"],
+    W: ["Willow", "Warden", "Wave", "Winter", "Wisp"],
+    X: ["Xenon", "Xylem", "Xavier", "Xylo", "Xerus"],
+    Y: ["Yarrow", "Yonder", "Yukon", "Yale", "Yogi"],
+    Z: ["Zenith", "Zephyr", "Zircon", "Zebra", "Zion"],
+};
+export function chooseTelegramThreadName(input) {
+    if (!input.slot || !/^[A-Z]$/.test(input.slot))
+        return undefined;
+    const names = TELEGRAM_THREAD_NAME_PALETTE[input.slot];
+    if (!names || names.length === 0)
+        return undefined;
+    const occupied = new Set((input.occupied ?? []).map((name) => getTelegramTopicIdentityName(name)));
+    const start = input.getRandom
+        ? Math.max(0, Math.min(names.length - 1, Math.floor(input.getRandom() * names.length)))
+        : getTelegramThreadNameEntropyIndex(input.entropy, names.length);
+    for (let offset = 0; offset < names.length; offset += 1) {
+        const name = names[(start + offset) % names.length];
+        if (!occupied.has(getTelegramTopicIdentityName(name)))
+            return name;
+    }
+    for (const paletteSlot of "ABCDEFGHIJKLMNOPQRSTUVWXYZ") {
+        for (const name of TELEGRAM_THREAD_NAME_PALETTE[paletteSlot] ?? []) {
+            if (!occupied.has(getTelegramTopicIdentityName(name)))
+                return name;
+        }
+    }
+    return undefined;
+}
+export function getTelegramThreadNameLeadingSlot(threadName) {
+    if (!threadName)
+        return undefined;
+    const first = getTelegramTopicIdentityName(threadName)[0];
+    return first && /^[A-Z]$/.test(first) ? first : undefined;
+}
+function getTelegramThreadNameEntropyIndex(entropy, length) {
+    if (length <= 1)
+        return 0;
+    if (typeof entropy === "number" && entropy < 1_000_000_000_000)
+        return 0;
+    const value = entropy === undefined ? "0" : String(entropy);
+    let hash = 2166136261;
+    for (const char of value) {
+        hash ^= char.codePointAt(0) ?? 0;
+        hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    return hash % length;
+}
+export function getTelegramTopicThreadNameValidationError(threadName, _slot) {
+    const identity = getTelegramTopicIdentityName(threadName);
+    const reasons = [];
+    if (!identity)
+        reasons.push("it is empty after trimming");
+    if (/\s/.test(identity))
+        reasons.push("it contains spaces");
+    if (/[^A-Za-z]/.test(identity)) {
+        reasons.push("it contains characters outside Latin A-Z letters");
+    }
+    if (!/^[A-Z]/.test(identity)) {
+        reasons.push("it does not start with an uppercase Latin letter");
+    }
+    const genericLabels = new Set(["telegram", "leader", "follower"]);
+    if (genericLabels.has(identity.toLowerCase())) {
+        reasons.push("it is a generic role label");
+    }
+    if (/^[A-Z]$/.test(identity))
+        reasons.push("it is only a bare slot letter");
+    if (reasons.length === 0)
+        return undefined;
+    return `Invalid Telegram instance name: ${reasons.join("; ")}. Use exactly one capitalized Latin word with no spaces, punctuation, emoji, non-Latin letters, or digits; it must not be a generic role label or only a bare slot letter.`;
+}
+export function getTelegramManualThreadDisplayNameValidationError(threadName) {
+    const trimmed = threadName.trim();
+    const normalized = trimmed.replace(/\s+/g, " ");
+    const reasons = [];
+    if (!trimmed)
+        reasons.push("it is empty after trimming");
+    if (trimmed && /[^\x20-\x7E]/.test(trimmed)) {
+        reasons.push("it contains characters outside printable ASCII");
+    }
+    if (normalized.length > 96)
+        reasons.push("it is longer than 96 characters");
+    if (/^[A-Z]$/.test(normalized)) {
+        reasons.push("a bare slot letter is reserved for reset to automatic");
+    }
+    if (reasons.length === 0)
+        return undefined;
+    return `Invalid Telegram Thread display name: ${reasons.join("; ")}. Use 1–96 printable ASCII characters.`;
+}
+export function isTelegramTopicThreadNameValidForSlot(threadName, slot) {
+    return !getTelegramTopicThreadNameValidationError(threadName, slot);
+}
+function applyTopicNameTemplate(template, request, slot) {
+    const threadName = request.threadName?.replace(/\s+/g, " ").trim() || request.profileKey;
+    let result = template
+        .replaceAll("{threadName}", threadName)
+        .replaceAll("{profileKey}", request.profileKey)
+        .replaceAll("{instanceId}", request.instanceId);
+    if (slot)
+        result = result.replaceAll("{slot}", slot);
+    return result;
+}
+export function getTelegramTopicName(request, template = "{slot}", slot) {
+    const name = applyTopicNameTemplate(template, request, slot)
+        .replace(/\s+/g, " ")
+        .trim();
+    return (name || slot || "Pi").slice(0, 128);
+}
+export function getTelegramTopicTitleForThreadName(threadName, slot, template = "{threadName}") {
+    return getTelegramTopicName({
+        instanceId: "",
+        profileKey: normalizeTelegramTopicTargetThreadName(threadName) || "Pi",
+        threadName,
+    }, template, slot);
+}

package/dist/lib/thread-reconciler.d.ts

@@ -192,6 +192,8 @@ export interface ThreadReconciliationApplyResult {
     incompleteActions?: ThreadReconciliationAction[];
 }
 export interface ThreadReconciliationApplyPorts {
+    /** Private-chat temporary tabs support deletion, not forum closing. */
+    skipCloseBeforeDelete?: boolean;
     isCleanupTargetProtected?: (target: ThreadTarget, action: ThreadReconciliationAction) => boolean;
     callApi?: <TResponse>(method: string, body: Record<string, unknown>) => Promise<TResponse>;
     markActiveByTarget?: (target: ThreadTarget) => boolean;

package/dist/lib/thread-reconciler.js

@@ -295,7 +295,7 @@ export async function applyThreadReconciliationPlan(plan, ports) {
             }
             let deleteConfirmed = false;
             let superseded = false;
-            for (const method of ["closeForumTopic", "deleteForumTopic"]) {
+            for (const method of ports.skipCloseBeforeDelete ? ["deleteForumTopic"] : ["closeForumTopic", "deleteForumTopic"]) {
                 if (ports.isCleanupTargetProtected?.(action.target, action)) {
                     superseded = true;
                     break;