@llblab/pi-kit 0.27.6 → 0.28.0

package/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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;