@llblab/pi-telegram 0.46.0 → 0.48.0

package/dist/lib/thread-display.js

@@ -0,0 +1,257 @@
+/**
+ * Telegram Workspace display projection
+ * Zones: telegram, tui, thread identity
+ * Owns mode-specific labels and serialized, authority-fenced title application.
+ * Excludes routing, name allocation, profile mutation, and live-owner discovery.
+ */
+import { isDeepStrictEqual } from "node:util";
+function labelText(value) {
+    return value.replace(/\s+/gu, " ").trim();
+}
+function boundedLabel(base, suffix = "") {
+    let prefix = "";
+    for (const character of base) {
+        if (prefix.length + character.length + suffix.length > 128)
+            break;
+        prefix += character;
+    }
+    return `${prefix}${suffix}`;
+}
+function directorySegments(cwd) {
+    return cwd.split("/").filter(Boolean);
+}
+function distinguishingDirectorySegments(cwd, directories) {
+    const parts = directorySegments(cwd);
+    if (!parts.length)
+        return [];
+    for (let depth = 1; depth <= parts.length; depth++) {
+        const candidate = labelText(parts.slice(-depth).join("/"));
+        const collides = directories.some((other) => other !== cwd &&
+            labelText(directorySegments(other).slice(-depth).join("/")).toLowerCase() ===
+                candidate.toLowerCase());
+        if (!collides)
+            return parts.slice(-depth);
+    }
+    return parts;
+}
+function directoryLabel(cwd, directories) {
+    const parts = distinguishingDirectorySegments(cwd, directories);
+    return parts.length ? labelText(parts.join("/")) : "/";
+}
+/** Pure directory tokenization shared by previews, initial titles, and reconciliation. */
+export function tokenizeTelegramDirectorySegment(segment) {
+    return segment
+        .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1\u0000$2")
+        .replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, "$1\u0000$2")
+        .split(/[^\p{L}\p{N}]+|\u0000/gu)
+        .filter(Boolean);
+}
+function formatDirectoryLabel(cwd, directories, mode) {
+    const segments = distinguishingDirectorySegments(cwd, directories);
+    if (!segments.length)
+        return "/";
+    const formatted = segments.map((segment) => {
+        const tokens = tokenizeTelegramDirectorySegment(segment);
+        if (!tokens.length)
+            return "";
+        if (mode === "directory-snake")
+            return tokens.map((token) => token.toLowerCase()).join("_");
+        return tokens.map((token) => /\p{L}/u.test(token) && token === token.toUpperCase()
+            ? token
+            : `${token.slice(0, 1).toUpperCase()}${token.slice(1).toLowerCase()}`).join(" ");
+    }).filter(Boolean);
+    if (!formatted.length)
+        return directoryLabel(cwd, directories);
+    return formatted.join(mode === "directory-snake" ? "_" : " / ");
+}
+/** Maps one leader-captured authenticated owner roster onto retained binding identities. */
+export function resolveTelegramLiveWorkspaceBindingKeys(bindings, leaderTarget, followers) {
+    const targets = new Set();
+    const add = (target) => {
+        if (target && typeof target.threadId === "number") {
+            targets.add(`${target.chatId}:${target.threadId}`);
+        }
+    };
+    add(leaderTarget);
+    for (const follower of followers)
+        add(follower.target);
+    return new Set(bindings.filter((binding) => targets.has(`${binding.target.chatId}:${binding.target.threadId}`)).map((binding) => binding.bindingKey));
+}
+/** Missing or ambiguous metadata yields no label rather than inventing identity. */
+export function resolveTelegramWorkspaceDisplayNames(bindings, mode, liveBindingKeys = new Set()) {
+    const labels = new Map();
+    const directories = Array.from(new Set(bindings.map((binding) => binding.cwd)));
+    const liveDirectoryCounts = new Map();
+    for (const binding of bindings) {
+        if (!liveBindingKeys.has(binding.bindingKey))
+            continue;
+        liveDirectoryCounts.set(binding.cwd, (liveDirectoryCounts.get(binding.cwd) ?? 0) + 1);
+    }
+    const bases = new Map();
+    for (const binding of bindings) {
+        const slot = binding.slot && /^[A-Z]$/u.test(binding.slot) ? binding.slot : undefined;
+        const manualName = binding.manualThreadName
+            ? labelText(binding.manualThreadName)
+            : undefined;
+        if (manualName) {
+            labels.set(binding.bindingKey, boundedLabel(manualName));
+        }
+        else if (mode === "letters") {
+            if (slot)
+                labels.set(binding.bindingKey, slot);
+        }
+        else if (mode === "names") {
+            const name = binding.threadName ? labelText(binding.threadName) : slot;
+            if (name)
+                labels.set(binding.bindingKey, boundedLabel(name));
+        }
+        else {
+            const base = mode === "directories"
+                ? directoryLabel(binding.cwd, directories)
+                : formatDirectoryLabel(binding.cwd, directories, mode);
+            bases.set(binding.bindingKey, base);
+            const showSuffix = mode === "directories"
+                ? binding.showSlotSuffix || bindings.filter((candidate) => candidate.cwd === binding.cwd).length > 1
+                : (liveDirectoryCounts.get(binding.cwd) ?? 0) > 1;
+            if (showSuffix && !slot)
+                continue;
+            const suffix = !showSuffix ? "" : mode === "directory-title"
+                ? ` ${slot}`
+                : `_${slot.toLowerCase()}`;
+            labels.set(binding.bindingKey, boundedLabel(base, suffix));
+        }
+    }
+    // Long or whitespace-normalized paths can collide even after qualification.
+    if (mode === "directories" || mode === "directory-snake" || mode === "directory-title") {
+        const counts = new Map();
+        for (const binding of bindings) {
+            const label = labels.get(binding.bindingKey);
+            if (!label || ((mode === "directory-snake" || mode === "directory-title") &&
+                !liveBindingKeys.has(binding.bindingKey)))
+                continue;
+            const key = label.toLowerCase();
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        for (const binding of bindings) {
+            const label = labels.get(binding.bindingKey);
+            if (binding.manualThreadName || !label ||
+                (counts.get(label.toLowerCase()) ?? 0) < 2)
+                continue;
+            if ((mode === "directory-snake" || mode === "directory-title") &&
+                (liveDirectoryCounts.get(binding.cwd) ?? 0) < 2) {
+                labels.delete(binding.bindingKey);
+                continue;
+            }
+            if (!binding.slot || !/^[A-Z]$/u.test(binding.slot)) {
+                labels.delete(binding.bindingKey);
+                continue;
+            }
+            labels.set(binding.bindingKey, boundedLabel(bases.get(binding.bindingKey), mode === "directory-title" ? ` ${binding.slot}` : `_${binding.slot.toLowerCase()}`));
+        }
+    }
+    const counts = new Map();
+    for (const binding of bindings) {
+        const label = labels.get(binding.bindingKey);
+        if (!label || ((mode === "directory-snake" || mode === "directory-title") &&
+            !liveBindingKeys.has(binding.bindingKey)))
+            continue;
+        const key = label.toLowerCase();
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    for (const [key, label] of labels) {
+        if ((counts.get(label.toLowerCase()) ?? 0) > 1)
+            labels.delete(key);
+    }
+    return labels;
+}
+export function resolveTelegramInitialWorkspaceDisplayName(input) {
+    const retained = input.bindings.find((binding) => binding.bindingKey === input.binding.bindingKey);
+    const binding = retained
+        ? {
+            ...input.binding,
+            ...(retained.showSlotSuffix ? { showSlotSuffix: true } : {}),
+            ...(input.preserveRetainedManualName !== false && retained.manualThreadName
+                ? { manualThreadName: retained.manualThreadName }
+                : {}),
+        }
+        : input.binding;
+    return resolveTelegramWorkspaceDisplayNames([
+        ...input.bindings.filter((candidate) => candidate.bindingKey !== binding.bindingKey),
+        binding,
+    ], input.mode, new Set([...(input.liveBindingKeys ?? []), binding.bindingKey])).get(binding.bindingKey);
+}
+export async function applyTelegramThreadDisplaySetting(mode, deps) {
+    const profile = deps.getProfileKey();
+    const setter = deps.ownsLeader() ? deps.getLeaderSetter() : deps.getFollowerSetter();
+    if (!setter)
+        throw new Error("Thread display settings require a connected compatible instance.");
+    await setter(mode);
+    if (deps.getProfileKey() !== profile)
+        throw new Error("Telegram Thread display setting changed profile.");
+    await deps.reloadConfig();
+    if (deps.getProfileKey() !== profile)
+        throw new Error("Telegram Thread display setting changed profile.");
+}
+/** Caller owns triggering and reporting; no timer or background retry is created. */
+export function createTelegramThreadDisplayReconciler(deps) {
+    let tail = Promise.resolve();
+    const apply = async () => {
+        const epoch = deps.getLeaderEpoch();
+        const profile = deps.getProfileKey();
+        const mode = deps.getMode();
+        const assertAuthority = () => {
+            if (epoch === undefined || deps.getLeaderEpoch() !== epoch ||
+                deps.getProfileKey() !== profile || deps.getMode() !== mode) {
+                throw new Error("Telegram Thread display update lost profile, mode, or leader authority.");
+            }
+        };
+        assertAuthority();
+        const bindings = deps.store.listWorkspaceBindings();
+        const liveBindingKeys = deps.captureLiveBindingKeys(bindings);
+        const titles = resolveTelegramWorkspaceDisplayNames(bindings, mode, liveBindingKeys);
+        let changed = 0;
+        for (const binding of bindings) {
+            const isBindingCurrent = deps.captureBindingAuthority(binding);
+            if (!isBindingCurrent)
+                continue;
+            const title = titles.get(binding.bindingKey);
+            if (!title)
+                throw new Error("Telegram Thread display identity is missing or ambiguous.");
+            const assertBinding = (expected) => {
+                assertAuthority();
+                const current = deps.store.listWorkspaceBindings().find((candidate) => candidate.bindingKey === expected.bindingKey);
+                if (!isDeepStrictEqual(current, expected) || !isBindingCurrent()) {
+                    throw new Error("Telegram Thread display binding changed.");
+                }
+            };
+            assertBinding(binding);
+            if ((binding.displayTitle ?? binding.threadName) === title)
+                continue;
+            await deps.callApi("editForumTopic", {
+                chat_id: binding.target.chatId,
+                message_thread_id: binding.target.threadId,
+                name: title,
+            }, { maxAttempts: 1 });
+            assertBinding(binding);
+            if (!deps.store.setWorkspaceDisplayTitle(binding, title)) {
+                throw new Error("Telegram Thread display binding changed before title commit.");
+            }
+            await deps.store.persist();
+            assertBinding({ ...binding, displayTitle: title });
+            changed++;
+        }
+        // A prior acknowledged edit may still have dirty metadata after a failed persist.
+        assertAuthority();
+        if (changed === 0)
+            await deps.store.persist();
+        assertAuthority();
+        return { changed };
+    };
+    return {
+        reconcile() {
+            const run = tail.then(apply);
+            tail = run.catch(() => undefined);
+            return run;
+        },
+    };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+import type { TelegramTarget } from "./target.ts";
+export declare const TELEGRAM_THREAD_NAME_DIALOG_TTL_MS: number;
+export type TelegramThreadNameDialogAction = "reset" | "cancel";
+export interface TelegramThreadNameDialogCandidate {
+    scope: string;
+    target: TelegramTarget;
+    dialogMessageId: number;
+    phase: "input";
+    expiresAtMs: number;
+}
+export declare function createTelegramThreadNameDialogRuntime(options?: {
+    ttlMs?: number;
+    nowMs?: () => number;
+}): {
+    open(input: {
+        scope: string;
+        target: TelegramTarget;
+        dialogMessageId: number;
+    }): TelegramThreadNameDialogCandidate;
+    select(input: {
+        scope: string;
+        target: TelegramTarget;
+        dialogMessageId: number;
+        action: TelegramThreadNameDialogAction;
+    }): {
+        kind: "reset" | "cancel" | "expired";
+    };
+    consumeName(input: {
+        scope: string;
+        target: TelegramTarget;
+        text: string;
+    }): {
+        kind: "name";
+        name: string;
+    } | {
+        kind: "none" | "empty";
+    };
+    clearScope(scope: string): void;
+    inspect(target: TelegramTarget): TelegramThreadNameDialogCandidate | undefined;
+};

package/dist/lib/thread-naming.js

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+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 } };
+}
+export function createTelegramThreadNameDialogRuntime(options) {
+    const ttlMs = options?.ttlMs ?? TELEGRAM_THREAD_NAME_DIALOG_TTL_MS;
+    const nowMs = options?.nowMs ?? Date.now;
+    const candidates = new Map();
+    const current = (scope, target) => {
+        const key = targetKey(target);
+        const candidate = candidates.get(key);
+        if (!candidate || candidate.scope !== scope ||
+            !sameTarget(candidate.target, target))
+            return undefined;
+        if (candidate.expiresAtMs <= nowMs()) {
+            candidates.delete(key);
+            return undefined;
+        }
+        return candidate;
+    };
+    return {
+        open(input) {
+            const candidate = {
+                scope: input.scope,
+                target: { ...input.target },
+                dialogMessageId: input.dialogMessageId,
+                phase: "input",
+                expiresAtMs: nowMs() + ttlMs,
+            };
+            candidates.set(targetKey(input.target), candidate);
+            return cloneCandidate(candidate);
+        },
+        select(input) {
+            const candidate = current(input.scope, input.target);
+            if (!candidate || candidate.dialogMessageId !== input.dialogMessageId) {
+                return { kind: "expired" };
+            }
+            candidates.delete(targetKey(input.target));
+            return { kind: input.action };
+        },
+        consumeName(input) {
+            const candidate = current(input.scope, input.target);
+            if (!candidate || candidate.phase !== "input")
+                return { kind: "none" };
+            const name = input.text.trim();
+            if (!name)
+                return { kind: "empty" };
+            candidates.delete(targetKey(input.target));
+            return { kind: "name", name };
+        },
+        clearScope(scope) {
+            for (const [key, candidate] of candidates) {
+                if (candidate.scope === scope)
+                    candidates.delete(key);
+            }
+        },
+        inspect(target) {
+            const candidate = candidates.get(targetKey(target));
+            if (!candidate || candidate.expiresAtMs <= nowMs()) {
+                candidates.delete(targetKey(target));
+                return undefined;
+            }
+            return cloneCandidate(candidate);
+        },
+    };
+}

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

@@ -0,0 +1,239 @@
+/**
+ * Telegram thread lifecycle reconciler
+ * Zones: telegram, multi-instance bus, synchronization control plane
+ * Owns pure planning for Telegram thread/tab lifecycle reconciliation and destructive topic cleanup authority
+ * Excludes live Telegram API calls, inbound routing, menu rendering, and direct thread-store persistence
+ */
+import type { TelegramTarget } from "./target.ts";
+type ThreadTarget = TelegramTarget & {
+    threadId: number;
+};
+type ThreadRecordStatus = "active" | "offline" | "stale" | "pending" | "starting" | "probe-required" | "failed";
+export interface ThreadReconciliationRecord {
+    target: ThreadTarget;
+    status: ThreadRecordStatus;
+    instanceId?: string;
+    profileKey?: string;
+    ownerKind?: "leader" | "manual-follower" | "pending-topic" | "legacy";
+}
+export interface ThreadReconciliationReservation {
+    target: ThreadTarget;
+    expiresAtMs?: number;
+}
+export interface ThreadReconciliationObservation {
+    target: ThreadTarget;
+    syncStatus: "open" | "closed" | "deleted" | "unknown";
+    observedAtMs: number;
+}
+export interface TelegramThreadPendingProvision {
+    id: string;
+    owner: "leader" | "manual-follower";
+    instanceId: string;
+    slot?: string;
+    target?: TelegramTarget & {
+        threadId: number;
+    };
+    startedAtMs: number;
+    expiresAtMs?: number;
+    leaderEpoch?: number | string;
+}
+export interface TelegramThreadCleanupIntent {
+    id: string;
+    owner: "leader" | "manual-follower";
+    instanceId: string;
+    runtimeGeneration: string;
+    profileKey?: string;
+    target: ThreadTarget;
+    requestedAtMs: number;
+}
+export interface TelegramUnboundThreadMessageObservation {
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    observedAtMs: number;
+    messageId?: number;
+    leaderEpoch?: number | string;
+}
+export interface TelegramReservedThreadMessageObservation {
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    observedAtMs: number;
+    messageId?: number;
+    leaderEpoch?: number | string;
+}
+export interface ReplacedInstanceBindingInput {
+    instanceId: string;
+    replacementTarget: ThreadTarget;
+}
+export interface PreviousLeaderCleanupInput {
+    currentInstanceId: string;
+}
+export type ThreadReconciliationAction = {
+    kind: "mark-topic-active";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "observed-open";
+} | {
+    kind: "mark-topic-stale";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    syncStatus: "closed" | "deleted";
+    reason: "observed-closed" | "observed-deleted";
+} | {
+    kind: "close-delete-unbound-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    observedAtMs: number;
+    messageId?: number;
+    reason: "unbound-user-message";
+    leaderEpoch?: number | string;
+} | {
+    kind: "close-delete-reserved-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    observedAtMs: number;
+    messageId?: number;
+    reason: "reserved-user-message" | "startup-reservation";
+    leaderEpoch?: number | string;
+} | {
+    kind: "close-stale-replaced-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "replaced-instance-binding";
+    instanceId?: string;
+    leaderEpoch?: number | string;
+} | {
+    kind: "close-delete-replaced-follower-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "replaced-follower";
+    instanceId?: string;
+    messageId?: number;
+    leaderEpoch?: number | string;
+} | {
+    kind: "close-delete-previous-leader-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "previous-leader";
+    instanceId?: string;
+    messageId?: number;
+    leaderEpoch?: number | string;
+} | {
+    kind: "close-delete-disconnected-instance-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "manual-disconnect";
+    instanceId?: string;
+    messageId?: number;
+    leaderEpoch?: number | string;
+} | {
+    kind: "close-delete-graceful-shutdown-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "graceful-shutdown";
+    cleanupIntentId: string;
+    instanceId: string;
+    runtimeGeneration: string;
+    leaderEpoch?: number | string;
+} | {
+    kind: "cancel-superseded-graceful-shutdown-cleanup";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "replacement-registration";
+    cleanupIntentId: string;
+    instanceId: string;
+    runtimeGeneration: string;
+    leaderEpoch?: number | string;
+} | {
+    kind: "close-delete-expired-pending-provision-topic";
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    reason: "expired-pending-provision";
+    pendingProvisionId: string;
+    instanceId?: string;
+    leaderEpoch?: number | string;
+};
+export type ThreadReconciliationPhase = "stable" | "provisioning" | "sync-required" | "cleanup-required";
+export type ThreadReconciliationEvent = "settled" | "pending-provision" | "sync-required" | "cleanup-required";
+export interface ThreadReconciliationMachineState {
+    phase: ThreadReconciliationPhase;
+    event: ThreadReconciliationEvent;
+    atMs: number;
+    leaderEpoch?: number | string;
+    pendingProvisionCount: number;
+    syncActionCount: number;
+    cleanupActionCount: number;
+}
+export interface ThreadReconciliationTransition {
+    from: ThreadReconciliationPhase;
+    to: ThreadReconciliationPhase;
+    event: ThreadReconciliationEvent;
+    atMs: number;
+}
+export interface ThreadReconciliationPlan {
+    actions: ThreadReconciliationAction[];
+    state?: ThreadReconciliationMachineState;
+    transition?: ThreadReconciliationTransition;
+}
+export interface ThreadReconciliationApplyResult {
+    changed: boolean;
+    incompleteActions?: ThreadReconciliationAction[];
+}
+export interface ThreadReconciliationApplyPorts {
+    isCleanupTargetProtected?: (target: ThreadTarget, action: ThreadReconciliationAction) => boolean;
+    callApi?: <TResponse>(method: string, body: Record<string, unknown>) => Promise<TResponse>;
+    markActiveByTarget?: (target: ThreadTarget) => boolean;
+    markStaleByTarget?: (target: ThreadTarget, syncStatus?: "closed" | "deleted", lastSyncError?: string) => boolean;
+    persist?: () => Promise<void>;
+    removePendingProvisionById?: (id: string) => boolean;
+    removeCleanupIntentById?: (id: string) => boolean;
+    getCurrentLeaderEpoch?: () => number | string | undefined;
+    recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
+}
+export interface ThreadReconciliationInput {
+    nowMs: number;
+    currentLeaderEpoch?: number | string;
+    records: readonly ThreadReconciliationRecord[];
+    reservations?: readonly ThreadReconciliationReservation[];
+    observations?: readonly ThreadReconciliationObservation[];
+    pendingProvisions?: readonly TelegramThreadPendingProvision[];
+    pendingCleanups?: readonly TelegramThreadCleanupIntent[];
+    unboundMessages?: readonly TelegramUnboundThreadMessageObservation[];
+    reservedMessages?: readonly TelegramReservedThreadMessageObservation[];
+    proactiveReservationCleanup?: boolean;
+    replacedBindings?: readonly ReplacedInstanceBindingInput[];
+    previousLeaderCleanup?: PreviousLeaderCleanupInput;
+    previousState?: ThreadReconciliationMachineState;
+    freshCreationGraceMs?: number;
+}
+export interface ThreadReconciliationRuntime {
+    getState: () => ThreadReconciliationMachineState | undefined;
+    recordPlan: (plan: ThreadReconciliationPlan) => void;
+    plan: (input: Omit<ThreadReconciliationInput, "previousState">) => ThreadReconciliationPlan;
+}
+export declare function createThreadReconciliationRuntime(deps: {
+    recordRuntimeEvent: (category: string, message: unknown, details?: Record<string, unknown>) => void;
+    scheduleSnapshotPersist: () => void;
+}): ThreadReconciliationRuntime;
+export declare function planDisconnectedInstanceThreadCleanup(input: {
+    target: TelegramTarget & {
+        threadId: number;
+    };
+    instanceId?: string;
+    leaderEpoch?: number | string;
+}): ThreadReconciliationPlan;
+export declare function applyThreadReconciliationPlan(plan: ThreadReconciliationPlan, ports: ThreadReconciliationApplyPorts): Promise<ThreadReconciliationApplyResult>;
+export declare function planThreadReconciliation(input: ThreadReconciliationInput): ThreadReconciliationPlan;
+export {};