@llblab/pi-kit 0.27.5 → 0.28.0

package/node_modules/@llblab/pi-telegram/dist/lib/recovery.d.ts

@@ -3,7 +3,6 @@
  * Zones: filesystem diagnostics, unclean-shutdown recovery
  * Owns fail-safe classification of temporary ownership and routing artifacts
  */
-import { renameSync } from "node:fs";
 import { type TelegramFileTransactionOptions } from "./locks.ts";
 export type TelegramRuntimeArtifactKind = "owners" | "state" | "transaction";
 export interface TelegramRuntimeCorruptArtifact {
@@ -35,19 +34,19 @@ export type TelegramRuntimeRecoveryResult = {
 } | {
     kind: "blocked-live-owner";
     livePids: number[];
-    quarantineDir?: string;
+    deletedPaths?: string[];
 } | {
     kind: "recovered";
     artifacts: TelegramRuntimeCorruptArtifact[];
-    quarantineDir: string;
+    /** Damaged disposable artifacts deleted per the approved corruption policy; nothing is quarantined. */
+    deletedPaths: string[];
 };
 export interface TelegramRuntimeRecoveryOptions extends TelegramRuntimeRecoveryClassificationOptions {
     recoveryTransactionPath?: string;
-    quarantineRoot?: string;
     pid?: number;
     getNowMs?: () => number;
-    quarantineRename?: typeof renameSync;
-    quarantineRenameRetryDelayMs?: number;
+    /** Fault-injection seam; production uses bounded-retry recursive removal. */
+    removePath?: (path: string) => void;
     transactionOptions?: TelegramFileTransactionOptions;
 }
 export type TelegramPollingStartRecoveryDecision = {
@@ -74,13 +73,34 @@ export interface TelegramPollingStartRecoveryHandlerDeps {
  */
 export declare function classifyTelegramRuntimeRecovery(options: TelegramRuntimeRecoveryClassificationOptions): TelegramRuntimeRecoveryClassification;
 /**
- * Quarantine classifier-approved disposable corruption under two guards.
+ * Delete classifier-approved disposable corruption under two guards.
  *
  * A dedicated recovery transaction serializes recoverers. The ownership
  * transaction then prevents a new Telegram owner from appearing between the
- * final classification and mutation. Every artifact is renamed within its
- * filesystem; durable config and diagnostics never enter the candidate set.
+ * final classification and mutation. Damaged ownership debris and canonical
+ * state are deleted (operator policy: unfinished Restores in unreadable state
+ * are acceptable loss). Durable config and diagnostics never enter the set.
  */
 export declare function recoverTelegramRuntimeState(options: TelegramRuntimeRecoveryOptions): TelegramRuntimeRecoveryResult;
+/**
+ * Remove recovery folders written by earlier releases (runtime root and session folders).
+ * Current releases delete damaged files instead of quarantining them; nothing reads these copies.
+ */
+export declare function removeTelegramLegacyRecoveryStorage(runtimeDir: string): string[];
+export interface TelegramSessionFolderSweeperDeps {
+    getSessionsDir: () => string;
+    getProfileName: () => string | undefined;
+    /** Sessions holding a Workspace slot binding, live registrations and this process's own session. */
+    getKeptSessionIds: () => Iterable<string | undefined>;
+    getNowMs?: () => number;
+    intervalMs?: number;
+}
+/**
+ * Leader housekeeping (operator policy): a session without a Workspace slot loses its
+ * current-profile journal family; the folder disappears once no profile uses it.
+ */
+export declare function createTelegramSessionFolderSweeper(deps: TelegramSessionFolderSweeperDeps): {
+    sweep: () => string[];
+};
 /** Build the `/telegram-connect` recovery boundary around runtime artifacts. */
 export declare function createTelegramPollingStartRecoveryHandler(deps: TelegramPollingStartRecoveryHandlerDeps): () => Promise<TelegramPollingStartRecoveryDecision>;

package/node_modules/@llblab/pi-telegram/dist/lib/recovery.js

@@ -3,10 +3,10 @@
  * Zones: filesystem diagnostics, unclean-shutdown recovery
  * Owns fail-safe classification of temporary ownership and routing artifacts
  */
-import { randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync, rmdirSync, rmSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { isProcessAlive as defaultIsProcessAlive, parseTelegramLockEntry, renameTelegramPathWithRetry, TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, withTelegramFileTransaction, } from "./locks.js";
+import { decodeTelegramSessionDirectoryName, getTelegramProfilePathSuffix } from "./paths.js";
+import { isProcessAlive as defaultIsProcessAlive, parseTelegramLockEntry, TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, withTelegramFileTransaction, } from "./locks.js";
 const OWNER_FILE_PATTERN = /^owner\.([A-Za-z0-9-]+)\.json$/u;
 const RECLAIM_FILE_PATTERN = /^owner\.reclaim\.(\d+)\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.json$/u;
 function corruption(kind, path, reason) {
@@ -40,6 +40,9 @@ function inspectState(path) {
     if (!existsSync(path))
         return { source: "state", ownerPids: [] };
     try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 8 * 1024 * 1024)
+            return corruption("state", path, `${basename(path)} cannot be safely inspected`);
         JSON.parse(readFileSync(path, "utf8"));
         return { source: "state", ownerPids: [] };
     }
@@ -136,19 +139,19 @@ export function classifyTelegramRuntimeRecovery(options) {
         : { kind: "recoverable-corruption", artifacts };
 }
 /**
- * Quarantine classifier-approved disposable corruption under two guards.
+ * Delete classifier-approved disposable corruption under two guards.
  *
  * A dedicated recovery transaction serializes recoverers. The ownership
  * transaction then prevents a new Telegram owner from appearing between the
- * final classification and mutation. Every artifact is renamed within its
- * filesystem; durable config and diagnostics never enter the candidate set.
+ * final classification and mutation. Damaged ownership debris and canonical
+ * state are deleted (operator policy: unfinished Restores in unreadable state
+ * are acceptable loss). Durable config and diagnostics never enter the set.
  */
 export function recoverTelegramRuntimeState(options) {
-    const pid = options.pid ?? process.pid;
     const transactionPath = options.transactionPath ?? `${options.ownersPath}.transaction`;
     const recoveryTransactionPath = options.recoveryTransactionPath ??
         join(dirname(options.ownersPath), "runtime-recovery.transaction");
-    const quarantineRoot = options.quarantineRoot ?? join(dirname(options.ownersPath), "recovery");
+    const removePath = options.removePath ?? ((path) => rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 }));
     const classificationOptions = {
         ownersPath: options.ownersPath,
         statePaths: options.statePaths,
@@ -167,29 +170,18 @@ export function recoverTelegramRuntimeState(options) {
                 livePids: initial.livePids,
             };
         }
-        let quarantineDir;
+        const deletedPaths = [];
         const recoveredArtifacts = [];
-        const ensureQuarantineDir = () => {
-            if (quarantineDir)
-                return quarantineDir;
-            quarantineDir = join(quarantineRoot, `${options.getNowMs?.() ?? Date.now()}-${pid}-${randomUUID()}`);
-            mkdirSync(quarantineDir, { recursive: true, mode: 0o700 });
-            return quarantineDir;
-        };
-        const quarantineArtifact = (artifact) => {
+        const deleteArtifact = (artifact) => {
             if (!existsSync(artifact.path))
                 return;
-            const destination = join(ensureQuarantineDir(), basename(artifact.path));
-            if (renameTelegramPathWithRetry(artifact.path, destination, {
-                rename: options.quarantineRename,
-                retryDelayMs: options.quarantineRenameRetryDelayMs,
-            })) {
-                recoveredArtifacts.push(artifact);
-            }
+            removePath(artifact.path);
+            deletedPaths.push(artifact.path);
+            recoveredArtifacts.push(artifact);
         };
         for (const artifact of initial.artifacts) {
             if (artifact.kind === "transaction")
-                quarantineArtifact(artifact);
+                deleteArtifact(artifact);
         }
         return withTelegramFileTransaction(transactionPath, () => {
             const current = classifyTelegramRuntimeRecovery({
@@ -200,25 +192,107 @@ export function recoverTelegramRuntimeState(options) {
                 return {
                     kind: "blocked-live-owner",
                     livePids: current.livePids,
-                    quarantineDir,
+                    ...(deletedPaths.length > 0 ? { deletedPaths } : {}),
                 };
             }
             if (current.kind === "recoverable-corruption") {
                 for (const artifact of current.artifacts) {
                     if (artifact.kind !== "transaction")
-                        quarantineArtifact(artifact);
+                        deleteArtifact(artifact);
                 }
             }
-            return recoveredArtifacts.length > 0 && quarantineDir
+            return recoveredArtifacts.length > 0
                 ? {
                     kind: "recovered",
                     artifacts: recoveredArtifacts,
-                    quarantineDir,
+                    deletedPaths,
                 }
                 : { kind: "not-needed" };
         }, options.transactionOptions);
     }, options.transactionOptions);
 }
+/**
+ * Remove recovery folders written by earlier releases (runtime root and session folders).
+ * Current releases delete damaged files instead of quarantining them; nothing reads these copies.
+ */
+export function removeTelegramLegacyRecoveryStorage(runtimeDir) {
+    const removed = [];
+    const remove = (path) => {
+        try {
+            if (!lstatSync(path).isDirectory())
+                return;
+            rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+            removed.push(path);
+        }
+        catch {
+            // Best-effort housekeeping; a later startup retries.
+        }
+    };
+    remove(join(runtimeDir, "recovery"));
+    let sessions = [];
+    try {
+        sessions = readdirSync(join(runtimeDir, "sessions"));
+    }
+    catch { /* no sessions yet */ }
+    for (const session of sessions)
+        remove(join(runtimeDir, "sessions", session, "recovery"));
+    return removed;
+}
+const TELEGRAM_SESSION_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
+/**
+ * Leader housekeeping (operator policy): a session without a Workspace slot loses its
+ * current-profile journal family; the folder disappears once no profile uses it.
+ */
+export function createTelegramSessionFolderSweeper(deps) {
+    const getNowMs = deps.getNowMs ?? Date.now;
+    const intervalMs = deps.intervalMs ?? TELEGRAM_SESSION_SWEEP_INTERVAL_MS;
+    let lastSweepAtMs;
+    return {
+        sweep() {
+            const now = getNowMs();
+            if (lastSweepAtMs !== undefined && now - lastSweepAtMs < intervalMs)
+                return [];
+            lastSweepAtMs = now;
+            const sessionsDir = deps.getSessionsDir();
+            const kept = new Set(deps.getKeptSessionIds());
+            const suffix = getTelegramProfilePathSuffix(deps.getProfileName()).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+            const family = new RegExp(`^journal\\.[a-f0-9]{16}${suffix}\\.json(?:\\.segments|\\.retained)?$`, "u");
+            const removed = [];
+            let names;
+            try {
+                names = readdirSync(sessionsDir);
+            }
+            catch {
+                return removed;
+            }
+            for (const name of names) {
+                const sessionId = decodeTelegramSessionDirectoryName(name);
+                if (sessionId === undefined || kept.has(sessionId))
+                    continue;
+                const folder = join(sessionsDir, name);
+                try {
+                    if (!lstatSync(folder).isDirectory())
+                        continue;
+                    for (const entry of readdirSync(folder)) {
+                        if (!family.test(entry))
+                            continue;
+                        const path = join(folder, entry);
+                        rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+                        removed.push(path);
+                    }
+                    if (readdirSync(folder).length === 0) {
+                        rmdirSync(folder);
+                        removed.push(folder);
+                    }
+                }
+                catch {
+                    // Best-effort housekeeping; the next sweep retries.
+                }
+            }
+            return removed;
+        },
+    };
+}
 /** Build the `/telegram-connect` recovery boundary around runtime artifacts. */
 export function createTelegramPollingStartRecoveryHandler(deps) {
     return async () => {
@@ -257,10 +331,7 @@ export function createTelegramPollingStartRecoveryHandler(deps) {
             });
         }
         try {
-            const recovery = recoverTelegramRuntimeState({
-                ownersPath,
-                statePaths,
-            });
+            const recovery = recoverTelegramRuntimeState({ ownersPath, statePaths });
             if (recovery.kind === "blocked-live-owner") {
                 return {
                     kind: "blocked",

package/node_modules/@llblab/pi-telegram/dist/lib/replies.d.ts

@@ -117,10 +117,6 @@ export declare function sendTelegramNativeMarkdownReply<TReplyMarkup = unknown>(
 }, options?: TelegramReplyTargetOptions & {
     replyMarkup?: TReplyMarkup;
 }): Promise<number | undefined>;
-export declare function sendTelegramNativeRichMessage(chatId: number, richMessage: TelegramInputRichMessage, deps: {
-    recordOwnership?: TelegramReplyOwnershipRecorder["record"];
-    sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
-}, options?: TelegramReplyTargetOptions): Promise<number>;
 export type TelegramAssistantRenderingMode = "rich" | "html";
 export interface TelegramRenderedMessageRuntimeDeps<TReplyMarkup> {
     renderTelegramMessage: (text: string, options?: {

package/node_modules/@llblab/pi-telegram/dist/lib/replies.js

@@ -498,7 +498,7 @@ export async function sendTelegramNativeMarkdownReply(chatId, replyToMessageId,
     }
     return lastMessageId;
 }
-export async function sendTelegramNativeRichMessage(chatId, richMessage, deps, options) {
+async function sendTelegramNativeRichMessage(chatId, richMessage, deps, options) {
     const sent = await deps.sendRichMessage({
         chat_id: chatId,
         rich_message: richMessage,

package/node_modules/@llblab/pi-telegram/dist/lib/routing.d.ts

@@ -7,6 +7,7 @@ import * as Bus from "./bus.ts";
 import * as Commands from "./commands.ts";
 import type { TelegramConfigStore } from "./config.ts";
 import type { TelegramInboundHandlerRuntime } from "./inbound.ts";
+import type { TelegramUpdateJournalQueuedCompletion, TelegramUpdateJournalQueuedReceiptEvidence } from "./journal.ts";
 import * as Media from "./media.ts";
 import * as Menu from "./menu.ts";
 import * as Model from "./model.ts";
@@ -15,11 +16,12 @@ import * as PromptTemplates from "./prompt-templates.ts";
 import * as Queue from "./queue.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
 import type { TelegramSectionRegistry } from "./sections.ts";
-import type { TelegramInputRichMessage } from "./telegram-api.ts";
+import type { TelegramApiCallOptions, TelegramInputRichMessage } from "./telegram-api.ts";
 import * as TextGroups from "./text-groups.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import type { TelegramInstanceThreadIdentityCandidate, TelegramTopicTargetRecord } from "./threads.ts";
 import * as Turns from "./turns.ts";
+import type { createTelegramWorkspaceExternalProtectionCapture } from "./workspace-retirement.ts";
 interface TelegramPromptPeerView {
     id?: unknown;
     is_bot?: unknown;
@@ -37,9 +39,37 @@ export declare function resolveTelegramGuestPromptPeer(input: {
     guestBotCallerChat?: TelegramPromptPeerView;
     ownerUserId?: number;
 }): string | undefined;
+/** Stable file scope of the remote Guest Mode peer: username, else numeric id; never the bot's own scope. */
+export declare function resolveTelegramGuestFileScope(input: Parameters<typeof resolveTelegramGuestPromptPeer>[0]): string;
 import * as Threads from "./threads.ts";
 import * as Updates from "./updates.ts";
+/** One admitted Restore attempt through recipient readiness, never source dispatch or cleanup. */
+export declare function advanceTelegramWorkspaceRestore(input: {
+    request: Threads.TelegramWorkspaceRestoreRequest;
+    authority: Threads.TelegramWorkspaceRestoreAuthority;
+    restoreStore: Threads.TelegramWorkspaceRestore;
+    getRecipient: () => Threads.TelegramWorkspaceRestoreRecipient | undefined;
+    /** Adapter proves current canonical ownership and authenticates observations; apply needs a fresh issuance. */
+    runRecipient: (input: {
+        intent: Threads.TelegramWorkspaceRestoreIntent;
+        mode: "apply" | "inspect";
+        isCurrent: () => boolean;
+    }) => Promise<{
+        operationId: string;
+        recipient: Threads.TelegramWorkspaceRestoreRecipient;
+        target: Threads.TelegramWorkspaceRestoreRequest["target"];
+        slot: string;
+        ready: boolean;
+    } | undefined>;
+    /**
+     * Recovery for a same-session successor already on the relocated target: it may receive the first grant, but only
+     * read-only inspection runs. It never commits a new relocation or applies a target.
+     */
+    inspectOnly?: true;
+}): Promise<Threads.TelegramWorkspaceRestoreIntent | undefined>;
 export declare const TELEGRAM_ALL_TAB_COMMAND_MAX_AGE_MS: number;
+/** One user-facing answer for expired or previous-process routing controls. */
+export declare const TELEGRAM_ROUTING_CHOICE_EXPIRED = "\u231B Routing choice expired.";
 export declare function isTelegramAllTabCommandExpired(message: {
     date?: number;
     message_thread_id?: number;
@@ -66,7 +96,7 @@ export interface TelegramInboundRouteRuntimeDeps<TMessage extends TelegramRouted
     configStore: Pick<TelegramConfigStore, "get" | "getAllowedUserId" | "persistAllowedUserId" | "persist"> & {
         set?: TelegramConfigStore["set"];
     };
-    callApi?: <TResponse>(method: string, body: Record<string, unknown>) => Promise<TResponse>;
+    callApi?: <TResponse>(method: string, body: Record<string, unknown>, options?: TelegramApiCallOptions) => Promise<TResponse>;
     getCurrentInstanceId?: () => string | undefined;
     getAdmissionScope?: () => string | undefined;
     getAdmissionJournalBinding?: () => string | undefined;
@@ -87,11 +117,32 @@ export interface TelegramInboundRouteRuntimeDeps<TMessage extends TelegramRouted
     handleTelegramTopicLifecycleUpdate?: (lifecycle: Updates.TelegramTopicLifecycleUpdate<TMessage>, ctx: TContext) => Promise<void> | void;
     handleTelegramThreadTargetObserved?: (target: Threads.TelegramTopicTargetRecord["target"], ctx: TContext) => Promise<void> | void;
     foreignOwnedUpdateForwarder?: Updates.TelegramForeignOwnedUpdateForwarder<TContext, Updates.TelegramMessageReactionUpdated, TCallbackQuery, TMessage>;
-    replaceFollowerThreadTarget?: (input: {
-        record: Threads.TelegramTopicTargetRecord;
-        target: Threads.TelegramTopicTargetRecord["target"];
-        oldTarget: Threads.TelegramTopicTargetRecord["target"];
-    }) => Promise<boolean>;
+    getWorkspaceRestoreStore?: () => Threads.TelegramWorkspaceRestore | undefined;
+    captureWorkspaceExternalProtection?: ReturnType<typeof createTelegramWorkspaceExternalProtectionCapture>;
+    /** Strict committed abandonment plus retained original; shared by Restore and temporary-input cancellation. */
+    inspectRestoreSourceAbandonment?: (updateId: number, journalBindingKey: string) => Threads.TelegramTemporaryThreadCancellationEvidence | undefined;
+    /** Strict active-journal observation only; a hint or missing source never substitutes for this ACK. */
+    inspectRestoreSourceCompletion?: (expected: Updates.TelegramDeferredSourceEvidence & {
+        completionSha256: string;
+    }) => (Updates.TelegramDeferredSourceEvidence & {
+        completionSha256: string;
+    }) | undefined;
+    inspectRestoreQueuedReceipt?: (expected: TelegramUpdateJournalQueuedCompletion & {
+        journalBindingKey: string;
+    }) => TelegramUpdateJournalQueuedReceiptEvidence | undefined;
+    hasWorkspaceRestoreAuthority?: () => boolean;
+    /** Strict complete namespace plus exact current/historical references; only an empty result clears journal protection. */
+    inspectTemporaryThreadSources?: (target: Queue.TelegramQueueTarget, requiredJournalBindingKeys: readonly string[]) => readonly number[] | undefined;
+    /** Quiet period after the last cancelled input before one cleanup attempt; defaults to 1000 ms. */
+    temporaryThreadCleanupDelayMs?: number;
+    getSessionGeneration?: () => number;
+    workspaceRestoreRecipient?: {
+        getSessionId: (ctx: TContext) => string | undefined;
+        getCwd: (ctx: TContext) => string | undefined;
+        getLeaderIdentity: Threads.TelegramLeaderThreadStateRuntime["getIdentity"];
+        followerRegistry: Pick<Bus.TelegramBusFollowerRegistry, "get" | "register">;
+        runFollower: ReturnType<typeof Bus.createTelegramBusWorkspaceRestoreController>;
+    };
     bridgeRuntime: TelegramBridgeRuntime;
     activeTurnRuntime: Queue.TelegramActiveTurnStore;
     mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage, TContext>;
@@ -183,7 +234,21 @@ export declare function createTelegramInboundRouteRuntime<TUpdate extends Update
     message?: TMessage;
     edited_message?: TMessage;
     callback_query?: TCallbackQuery;
-}, TMessage extends TelegramRoutedMessage, TCallbackQuery extends TelegramRoutedCallbackQuery, TContext, TModel extends Model.MenuModel>(deps: TelegramInboundRouteRuntimeDeps<TMessage, TCallbackQuery, TContext, TModel>): Updates.TelegramUpdateRuntimeController<TContext, TUpdate>;
+}, TMessage extends TelegramRoutedMessage, TCallbackQuery extends TelegramRoutedCallbackQuery, TContext, TModel extends Model.MenuModel>(deps: TelegramInboundRouteRuntimeDeps<TMessage, TCallbackQuery, TContext, TModel>): Updates.TelegramUpdateRuntimeController<TContext, TUpdate> & {
+    expireRoutingInput: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["expireRoutingInput"]>;
+    shouldReviewHistoricalInput: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["shouldReviewHistoricalInput"]>;
+    shouldHoldPendingInput: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["shouldHoldPendingInput"]>;
+    forgetPreviousWorld(input: Updates.TelegramHeldSourcePreparation<TContext>, captureTransport?: (ctx: TContext) => (() => boolean) | undefined): Promise<{
+        forgotten: number;
+        deleted: number;
+    }>;
+    beforeQueueReceiptPublished: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["beforeQueueReceiptPublished"]>;
+    onQueueReceiptCommitted: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["onQueueReceiptCommitted"]>;
+    onQueueReceiptCompleted: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["onQueueReceiptCompleted"]>;
+    onUpdateCompleted: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["onUpdateCompleted"]>;
+    onWorkspaceRestoreRecipientObserved(follower: Bus.TelegramBusFollowerView, isCurrent: () => boolean, ctx: TContext | undefined): Promise<void> | undefined;
+    waitForRestoreSettlement(): Promise<void>;
+};
 export interface TelegramAssistantOutputAuthority<TTransportStamp> {
     transportStamp: TTransportStamp;
     route: "direct" | "follower" | "none";