@llblab/pi-telegram 0.52.1 → 0.53.0

package/dist/lib/sync.js

@@ -3,13 +3,13 @@
  * Zones: Telegram bot reality mirror, demand-driven reconciliation, status diagnostics
  * Owns pure contracts for deciding when local Telegram mirror state should be refreshed without querying Telegram on every action
  */
-import { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError } from "./telegram-api.js";
 import { getTelegramTargetKey } from "./target.js";
+import { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError, } from "./telegram-api.js";
 import * as ThreadReconciler from "./thread-reconciler.js";
-import { TelegramWorkspaceSlotUnavailableError } from "./workspace-slots.js";
-import { normalizeTelegramWorkspacePath } from "./workspace-identity.js";
+import { commitTelegramWorkspaceProvisionBinding, createTelegramCleanupTargetProtection, getTelegramTargetFromApiBody, getTelegramThreadOwnerKey, isSameTelegramProcessInstance, isTelegramTopicTargetStaleError, provisionOwnBusTopic, } from "./threads.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
-import { createTelegramCleanupTargetProtection, commitTelegramWorkspaceProvisionBinding, getTelegramTargetFromApiBody, getTelegramThreadOwnerKey, isSameTelegramProcessInstance, isTelegramTopicTargetStaleError, provisionOwnBusTopic, } from "./threads.js";
+import { normalizeTelegramWorkspacePath } from "./workspace-identity.js";
+import { TelegramWorkspaceSlotUnavailableError } from "./workspace-slots.js";
 function markTelegramConfigSyncChange(state, action, options) {
     const nowMs = options?.nowMs ?? Date.now();
     let nextState = markTelegramSyncSliceFresh(state, "pairing", {
@@ -32,10 +32,13 @@ export function createTelegramPreservedLeaderQuitHandler(deps) {
         const profile = deps.getProfileName();
         if (epoch === undefined || !isSessionCurrent())
             return undefined;
-        const isCurrent = () => isSessionCurrent() && deps.getCurrentLeaderEpoch() === epoch &&
-            deps.getProfileName() === profile && deps.isPollingSuspended();
+        const isCurrent = () => isSessionCurrent() &&
+            deps.getCurrentLeaderEpoch() === epoch &&
+            deps.getProfileName() === profile &&
+            deps.isPollingSuspended();
         return async () => {
-            if (!isCurrent() || await deps.resolveAutomaticThreadCleanupEnabled() !== false)
+            if (!isCurrent() ||
+                (await deps.resolveAutomaticThreadCleanupEnabled()) !== false)
                 return;
             if (!isCurrent())
                 return;
@@ -49,13 +52,20 @@ export function createTelegramPreservedLeaderQuitHandler(deps) {
                 await deps.topicTargetStore.load();
                 if (!isCurrent())
                     return;
-                const records = deps.topicTargetStore.list().filter((record) => record.instanceId === deps.instanceId && (record.status === "active" || record.status === "starting"));
+                const records = deps.topicTargetStore
+                    .list()
+                    .filter((record) => record.instanceId === deps.instanceId &&
+                    (record.status === "active" || record.status === "starting"));
                 if (records.length !== 1)
                     return;
                 const record = records[0];
-                if (deps.topicTargetStore.listPendingCleanups().some((intent) => intent.target.chatId === record.target.chatId && intent.target.threadId === record.target.threadId))
+                if (deps.topicTargetStore
+                    .listPendingCleanups()
+                    .some((intent) => intent.target.chatId === record.target.chatId &&
+                    intent.target.threadId === record.target.threadId))
                     return;
-                if (!await deps.topicTargetStore.detachTargetOwner(record, isCurrent) && isCurrent()) {
+                if (!(await deps.topicTargetStore.detachTargetOwner(record, isCurrent)) &&
+                    isCurrent()) {
                     throw new Error("Telegram preserved leader detachment was not committed.");
                 }
             });
@@ -74,11 +84,47 @@ function createTelegramSessionRestartThreadCleanupHandler(deps) {
 }
 export function createTelegramThreadDisconnectAssembly(deps) {
     return {
-        disconnect: createTelegramManualThreadDisconnectHandler({
-            ...deps,
-            workspaceOperationKind: "workspace.disconnect-thread",
-            stopPolling: deps.stopPolling,
-        }),
+        async disconnect() {
+            const captured = deps.captureStopPolling?.();
+            const stop = captured?.stop ?? deps.stopPolling;
+            let stopAttempted = false;
+            const disconnect = createTelegramManualThreadDisconnectHandler({
+                ...deps,
+                workspaceOperationKind: "workspace.disconnect-thread",
+                isDisconnectCurrent: captured?.isCurrent ?? deps.isDisconnectCurrent,
+                stopPolling() {
+                    stopAttempted = true;
+                    return stop();
+                },
+            });
+            try {
+                return await disconnect();
+            }
+            catch (error) {
+                // Never retry a stop whose teardown/release outcome may already have committed.
+                if (stopAttempted) {
+                    deps.recordRuntimeEvent("connection", error, {
+                        phase: "disconnect-stop",
+                    });
+                    throw error;
+                }
+                deps.recordRuntimeEvent("connection", error, {
+                    phase: "disconnect-cleanup",
+                });
+                let stopped;
+                try {
+                    stopped = await stop();
+                }
+                catch (stopError) {
+                    deps.recordRuntimeEvent("connection", stopError, {
+                        phase: "disconnect-stop",
+                    });
+                    throw stopError;
+                }
+                const separator = /[.!?]$/u.test(stopped) ? " " : ". ";
+                return `${stopped}${separator}Thread cleanup was not confirmed. Check /telegram-status --debug.`;
+            }
+        },
         cleanupForSessionRestart: createTelegramSessionRestartThreadCleanupHandler({
             ...deps,
             suspendPolling: deps.suspendPolling,
@@ -86,7 +132,12 @@ export function createTelegramThreadDisconnectAssembly(deps) {
     };
 }
 export function createTelegramManualThreadDisconnectHandler(deps) {
+    const assertCurrent = () => {
+        if (deps.isDisconnectCurrent?.() === false)
+            throw new Error("Telegram disconnect was superseded by a new connection.");
+    };
     const operation = async () => {
+        assertCurrent();
         const currentRecord = deps.getCurrentThreadRecord();
         let cleanupPending = false;
         if (currentRecord?.target.threadId) {
@@ -98,6 +149,7 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
             if (isManualFollower && !ownsLeader) {
                 if (deps.disconnectFollowerThread) {
                     const disconnected = await deps.disconnectFollowerThread();
+                    assertCurrent();
                     if (!disconnected) {
                         throw new Error("Telegram follower thread deletion requires a live leader registration.");
                     }
@@ -117,11 +169,15 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
                     target,
                     requestedAtMs: (deps.getNowMs ?? Date.now)(),
                 };
-                const departingRecord = deps.topicTargetStore.list().find((record) => record.instanceId === currentRecord.instanceId &&
-                    record.target.chatId === target.chatId && record.target.threadId === target.threadId);
+                const departingRecord = deps.topicTargetStore
+                    .list()
+                    .find((record) => record.instanceId === currentRecord.instanceId &&
+                    record.target.chatId === target.chatId &&
+                    record.target.threadId === target.threadId);
                 const isCleanupTargetProtected = createTelegramCleanupTargetProtection(deps.topicTargetStore, departingRecord);
                 deps.topicTargetStore.upsertPendingCleanup(intent);
                 await deps.topicTargetStore.persist();
+                assertCurrent();
                 const cleanupPlan = ThreadReconciler.planThreadReconciliation({
                     nowMs: (deps.getNowMs ?? Date.now)(),
                     currentLeaderEpoch: leaderEpoch,
@@ -131,20 +187,25 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
                 const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(cleanupPlan, {
                     isCleanupTargetProtected,
                     callApi(method, body) {
+                        assertCurrent();
                         return deps.callApi(method, body);
                     },
                     markStaleByTarget(targetToMark, syncStatus, lastSyncError) {
+                        assertCurrent();
                         return deps.topicTargetStore.markStaleByTarget(targetToMark, syncStatus, lastSyncError);
                     },
                     removeCleanupIntentById(id) {
+                        assertCurrent();
                         return deps.topicTargetStore.removePendingCleanup(id);
                     },
                     persist() {
+                        assertCurrent();
                         return deps.topicTargetStore.persist();
                     },
                     getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
                     recordRuntimeEvent: deps.recordRuntimeEvent,
                 });
+                assertCurrent();
                 if (cleanupPlan.actions.some((action) => isCleanupTargetProtected(action.target, action))) {
                     return "Thread disconnect superseded by a new binding.";
                 }
@@ -160,6 +221,7 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
                 action: "manual-disconnect",
             }));
         }
+        assertCurrent();
         const stopped = await deps.stopPolling();
         return cleanupPending
             ? `${stopped} Telegram thread cleanup remains pending for the next leader.`
@@ -269,23 +331,32 @@ export function captureTelegramStaleTargetRequestRecovery(body, deps) {
     if (!target || epoch === undefined)
         return undefined;
     const key = getTelegramTargetKey(target);
-    const record = deps.topicTargetStore.list().find((candidate) => getTelegramTargetKey(candidate.target) === key);
+    const record = deps.topicTargetStore
+        .list()
+        .find((candidate) => getTelegramTargetKey(candidate.target) === key);
     if (!record)
         return undefined;
     const generation = deps.getSessionGeneration();
     const profile = deps.getProfileName();
     const isAuthorityCurrent = () => deps.getCurrentLeaderEpoch() === epoch &&
-        deps.getSessionGeneration() === generation && deps.getProfileName() === profile;
+        deps.getSessionGeneration() === generation &&
+        deps.getProfileName() === profile;
     const isCurrent = () => {
-        const current = deps.topicTargetStore.list().find((candidate) => getTelegramTargetKey(candidate.target) === key);
-        return isAuthorityCurrent() &&
-            current?.instanceId === record.instanceId && current?.profileKey === record.profileKey &&
-            current?.updatedAtMs === record.updatedAtMs && current?.createdAtMs === record.createdAtMs;
+        const current = deps.topicTargetStore
+            .list()
+            .find((candidate) => getTelegramTargetKey(candidate.target) === key);
+        return (isAuthorityCurrent() &&
+            current?.instanceId === record.instanceId &&
+            current?.profileKey === record.profileKey &&
+            current?.updatedAtMs === record.updatedAtMs &&
+            current?.createdAtMs === record.createdAtMs);
     };
     return async (error) => {
         const requestTarget = getTelegramApiErrorRequestTarget(error);
-        if (!isTelegramStaleTargetHttpError(error) || !requestTarget ||
-            getTelegramTargetKey(requestTarget) !== key || !isCurrent())
+        if (!isTelegramStaleTargetHttpError(error) ||
+            !requestTarget ||
+            getTelegramTargetKey(requestTarget) !== key ||
+            !isCurrent())
             return;
         if (await recoverStaleTelegramTopicApiError({ chat_id: target.chatId, message_thread_id: target.threadId }, error, { ...deps, isCurrent, isAuthorityCurrent })) {
             deps.onRecovered();
@@ -311,7 +382,7 @@ export async function recoverStaleTelegramTopicApiError(apiBody, error, deps) {
     const recover = async () => {
         if (deps.isCurrent) {
             if (!deps.topicTargetStore.invalidateTarget ||
-                !await deps.topicTargetStore.invalidateTarget(target, deps.isCurrent, String(error)))
+                !(await deps.topicTargetStore.invalidateTarget(target, deps.isCurrent, String(error))))
                 return false;
             if (deps.isAuthorityCurrent?.() === false)
                 return false;
@@ -393,7 +464,12 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
     const legacyLeaderRecord = deps.topicTargetStore.getByProfileKey(leaderProfileKey);
     let capacityUnavailable = false;
     const workspaceIdentity = normalizedLeaderCwd
-        ? deps.topicTargetStore.claimWorkspaceIdentity(normalizedLeaderCwd, deps.instanceId, legacyLeaderRecord?.instanceId, { sessionId: deps.sessionId, onCapacityUnavailable() { capacityUnavailable = true; } })
+        ? deps.topicTargetStore.claimWorkspaceIdentity(normalizedLeaderCwd, deps.instanceId, legacyLeaderRecord?.instanceId, {
+            sessionId: deps.sessionId,
+            onCapacityUnavailable() {
+                capacityUnavailable = true;
+            },
+        })
         : undefined;
     if (deps.cwd && !workspaceIdentity) {
         if (capacityUnavailable)
@@ -428,7 +504,9 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
             target: { ...committed.target },
             slot: committed.slot ?? result.slot,
             ...(committed.threadName ? { threadName: committed.threadName } : {}),
-            ...(committed.displayTitle ? { displayTitle: committed.displayTitle } : {}),
+            ...(committed.displayTitle
+                ? { displayTitle: committed.displayTitle }
+                : {}),
         };
     };
     try {
@@ -469,7 +547,9 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
                 ...(legacyLeaderRecord.threadName
                     ? { threadName: legacyLeaderRecord.threadName }
                     : {}),
-                ...(legacyLeaderRecord.slot ? { slot: legacyLeaderRecord.slot } : {}),
+                ...(legacyLeaderRecord.slot
+                    ? { slot: legacyLeaderRecord.slot }
+                    : {}),
                 updatedAtMs: legacyLeaderRecord.updatedAtMs,
             }
             : undefined;
@@ -557,7 +637,9 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
         });
         // Legacy callers without session identity may reuse the active instance target.
         // Session-aware callers must resolve their exact Workspace binding instead.
-        if (deps.sessionId === undefined && !deps.forceFreshUnnamed && priorTargets.length > 0) {
+        if (deps.sessionId === undefined &&
+            !deps.forceFreshUnnamed &&
+            priorTargets.length > 0) {
             const record = priorTargets[0];
             deps.recordEvent("telegram", "Leader thread preserved after session lifecycle change", {
                 phase: "leader-thread-reused",
@@ -704,21 +786,6 @@ export function createTelegramProvisioningActivityRuntime() {
         },
     };
 }
-const RECONCILE_TRIGGERS = new Set([
-    "startup",
-    "reload",
-    "topic-lifecycle",
-    "stale-api-error",
-    "setup-change",
-    "pairing-change",
-    "follower-register",
-    "follower-prune",
-    "status-request",
-    "leader-health-tick",
-]);
-export function shouldReconcileTelegramSync(trigger) {
-    return RECONCILE_TRIGGERS.has(trigger);
-}
 export function markTelegramSyncSliceSuspect(state, slice, input) {
     return {
         ...state,

package/dist/lib/target.d.ts

@@ -18,3 +18,7 @@ export declare function areTelegramTargetsEqual(left: TelegramTarget, right: Tel
 export declare function getTelegramTargetThreadParams(target: TelegramTarget): {
     message_thread_id?: number;
 };
+/** Pure wire parser for `{ chatId, threadId? }`; unknown fields are dropped and malformed shapes refuse. */
+export declare function parseTelegramTarget(value: unknown): TelegramTarget | undefined;
+/** Pure Bot API integer id parser accepting integer numbers or non-blank integer strings. */
+export declare function parseTelegramIntegerId(value: unknown): number | undefined;

package/dist/lib/target.js

@@ -25,3 +25,21 @@ export function getTelegramTargetThreadParams(target) {
         ? { message_thread_id: target.threadId }
         : {};
 }
+/** Pure wire parser for `{ chatId, threadId? }`; unknown fields are dropped and malformed shapes refuse. */
+export function parseTelegramTarget(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const { chatId, threadId } = value;
+    if (typeof chatId !== "number")
+        return undefined;
+    return typeof threadId === "number" ? { chatId, threadId } : { chatId };
+}
+/** Pure Bot API integer id parser accepting integer numbers or non-blank integer strings. */
+export function parseTelegramIntegerId(value) {
+    if (typeof value === "number" && Number.isInteger(value))
+        return value;
+    if (typeof value !== "string" || value.trim() === "")
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) ? parsed : undefined;
+}

package/dist/lib/telegram-api.d.ts

@@ -7,7 +7,8 @@
  */
 import type { TelegramAttachmentSource } from "./media.ts";
 export declare const TELEGRAM_FILE_MAX_BYTES: number;
-export declare function getTelegramInboundFileByteLimitFromEnv(env: NodeJS.ProcessEnv, names: string[], defaultValue?: number): number;
+/** First positive safe-integer byte limit among ordered env names, else the caller's default. */
+export declare function getTelegramByteLimitFromEnv(env: NodeJS.ProcessEnv, names: readonly string[], defaultValue: number): number;
 export type TelegramNetworkFamilyPolicy = "auto" | "ipv4" | "ipv6" | "ipv4-fallback";
 type TelegramNetworkFamily = 4 | 6;
 export interface TelegramUser {
@@ -288,6 +289,8 @@ export interface TelegramApiRetryWait {
     retryAfterSeconds?: number;
 }
 export interface TelegramApiCallOptions {
+    /** Local per-call effect authority; independent of source completion and transport ownership. */
+    assertAuthority?: () => void;
     signal?: AbortSignal;
     maxAttempts?: number;
     retryRateLimit?: boolean;
@@ -297,6 +300,12 @@ export interface TelegramApiCallOptions {
     /** Observability hook fired before a 429 retry wait, never for 5xx waits. */
     onRetryWait?: (wait: TelegramApiRetryWait) => void;
 }
+export declare class TelegramApiAuthorityError extends Error {
+    readonly requestIssued: boolean;
+    constructor(requestIssued: boolean);
+}
+/** Recheck caller authority, classifying refusal by whether a Bot API request was already issued. */
+export declare function assertTelegramApiCallAuthority(assertAuthority: (() => void) | undefined, requestIssued: boolean): void;
 export interface TelegramFileDownloadOptions {
     signal?: AbortSignal;
     maxFileSizeBytes?: number;
@@ -338,14 +347,14 @@ export interface TelegramEditGuestInlineMessageContent {
     richMessage?: TelegramInputRichMessage;
     parseMode?: "HTML";
 }
-export interface TelegramAnswerCallbackQueryOptions {
+export interface TelegramAnswerCallbackQueryOptions extends Pick<TelegramApiCallOptions, "assertAuthority"> {
     recordRuntimeEvent?: (kind: "api", error: unknown, details?: Record<string, unknown>) => void;
 }
 export interface TelegramApiClient {
     call: <TResponse>(method: string, body: Record<string, unknown>, options?: TelegramApiCallOptions) => Promise<TResponse>;
     callMultipart: <TResponse>(method: string, fields: Record<string, string>, fileField: string, filePath: string, fileName: string, options?: TelegramApiCallOptions) => Promise<TResponse>;
     downloadFile: (fileId: string, suggestedName: string, tempDir: string, options?: TelegramFileDownloadOptions) => Promise<string>;
-    answerCallbackQuery: (callbackQueryId: string, text?: string) => Promise<void>;
+    answerCallbackQuery: (callbackQueryId: string, text?: string, options?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<void>;
     answerGuestQuery?: (guestQueryId: string, text?: string, options?: TelegramAnswerGuestQueryOptions) => Promise<void>;
 }
 export interface TelegramApiTargetActivityRuntime {
@@ -422,16 +431,14 @@ export interface TelegramBridgeApiRuntimeDeps {
     chatActionMinIntervalMs?: number;
     chatActionMaxGates?: number;
 }
-export interface TelegramBridgeApiRuntime {
-    call: <TResponse>(method: string, body: Record<string, unknown>, options?: TelegramApiCallOptions) => Promise<TResponse>;
-    callMultipart: <TResponse>(method: string, fields: Record<string, string>, fileField: string, filePath: string, fileName: string, options?: TelegramApiCallOptions) => Promise<TResponse>;
+export interface TelegramBridgeApiRuntime extends Pick<TelegramApiClient, "call" | "callMultipart"> {
     downloadFile: (fileId: string, suggestedName: string, source?: TelegramAttachmentSource) => Promise<string>;
     deleteWebhook: (signal?: AbortSignal) => Promise<boolean>;
     getUpdates: (body: Record<string, unknown>, signal?: AbortSignal) => Promise<TelegramUpdate[]>;
     setMyCommands: (commands: readonly {
         command: string;
         description: string;
-    }[]) => Promise<boolean>;
+    }[], options?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<boolean>;
     sendChatAction: (chatId: number, action: string, options?: {
         message_thread_id?: number;
     }) => Promise<boolean>;
@@ -446,12 +453,12 @@ export interface TelegramBridgeApiRuntime {
         entities?: unknown[];
         message_thread_id?: number;
     }) => Promise<boolean>;
-    sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
-    sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
+    sendMessage: (body: TelegramSendMessageBody, options?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<TelegramSentMessage>;
+    sendRichMessage: (body: TelegramSendRichMessageBody, options?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<TelegramSentMessage>;
     sendRichMessageDraft: (body: TelegramSendRichMessageDraftBody) => Promise<boolean>;
-    editMessageText: (body: TelegramEditMessageTextBody) => Promise<"edited" | "unchanged">;
+    editMessageText: (body: TelegramEditMessageTextBody, options?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<"edited" | "unchanged">;
     editMessageReplyMarkup: (chatId: number, messageId: number, replyMarkup: unknown) => Promise<void>;
-    answerCallbackQuery: (callbackQueryId: string, text?: string) => Promise<void>;
+    answerCallbackQuery: (callbackQueryId: string, text?: string, options?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<void>;
     answerGuestQuery: (guestQueryId: string, text?: string, options?: TelegramAnswerGuestQueryOptions) => Promise<void>;
     /**
      * Temporary Guest Mode ACK experiment: answers the guest query and returns
@@ -514,8 +521,6 @@ export declare function fetchTelegramBotIdentity(botToken: string, fetchImpl?: t
  */
 export declare function callTelegramMultipart<TResponse>(botToken: string | undefined, method: string, fields: Record<string, string>, fileField: string, filePath: string, fileName: string, options?: TelegramApiCallOptions): Promise<TResponse>;
 export declare function downloadTelegramFile(botToken: string | undefined, fileId: string, suggestedName: string, tempDir: string, options?: TelegramFileDownloadOptions): Promise<string>;
-/** Tooltip-like callback answers omit a terminal sentence period; ellipses and other punctuation stay literal. */
-export declare function formatTelegramCallbackAnswerText(text: string | undefined): string | undefined;
 export declare function answerTelegramCallbackQuery(botToken: string | undefined, callbackQueryId: string, text?: string, options?: TelegramAnswerCallbackQueryOptions): Promise<void>;
 export declare function createTelegramChatActionSender<TAction extends string>(sendChatAction: (chatId: number, action: TAction, options?: {
     message_thread_id?: number;