@llblab/pi-kit 0.27.6 → 0.28.0

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

@@ -121,8 +121,6 @@ export interface TelegramSectionRuntimeDeps {
     deleteMessage: (chatId: number, messageId: number) => Promise<void>;
 }
 /** @internal */
-export declare function setGlobalTelegramSectionRegistry(registry: TelegramSectionRegistry): void;
-/** @internal */
 export declare function createAndBindTelegramSectionRegistry(): TelegramSectionRegistry;
 /**
  * Register a Telegram Extension Section from any pi extension.

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

@@ -51,7 +51,7 @@ function buildTelegramSectionCallbackContext(sectionId, token, chatId, messageId
 }
 // --- GlobalThis Bridge ---
 /** @internal */
-export function setGlobalTelegramSectionRegistry(registry) {
+function setGlobalTelegramSectionRegistry(registry) {
     globalThis[SECTION_REGISTRY_KEY] = registry;
 }
 /** @internal */

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

@@ -1,7 +1,8 @@
 /**
  * Telegram status rendering helpers
  * Zones: telegram ui, pi agent diagnostics, tui
- * Owns status summaries, redacted runtime diagnostics, and compact connection-failure copy
+ * Owns status summaries, redacted diagnostics, projection lifecycle and compact connection-failure copy
+ * Excludes canonical state, transport admission and filesystem policy
  */
 /** UI copy is allowlisted; raw exception text belongs only in redacted diagnostics. */
 export declare function formatTelegramConnectionFailure(error: unknown): string;
@@ -378,7 +379,6 @@ export interface TelegramStatusRuntime<TContext extends TelegramStatusRuntimeCon
     getStatusLines: (options?: TelegramBridgeStatusLineOptions) => string[];
     getStatusState: () => TelegramBridgeStatusLineState;
 }
-export declare function redactTelegramRuntimeMessage(message: string, botToken: string | undefined): string;
 export declare function recordStructuredTelegramRuntimeEvent(events: TelegramRuntimeEvent[], input: TelegramRuntimeEventInput, options: {
     botToken?: string;
     maxEvents: number;
@@ -394,7 +394,6 @@ export declare function recordStructuredTelegramRuntimeEvent(events: TelegramRun
 export declare function registerTelegramStatusLineProvider(provider: TelegramStatusLineProvider, options: {
     id: string;
 }): () => void;
-export declare function getTelegramStatusLineProviderResults(ctx: TelegramStatusLineProviderContext): TelegramStatusLineProviderResult[];
 export declare function clearTelegramStatusLineProviders(): void;
 export declare function createTelegramRuntimeEventRecorder(options: TelegramRuntimeEventRecorderOptions): TelegramRuntimeEventRecorder;
 export declare function buildTelegramRuntimeEventLines(events: TelegramRuntimeEvent[]): string[];
@@ -418,18 +417,56 @@ export declare function createTelegramRuntimeLogScope(input: {
     state: TelegramBridgeStatusLineState;
     instanceId: string;
 }): TelegramRuntimeLogScope;
-export declare function createTelegramStatusSnapshot(state: TelegramBridgeStatusLineState): {
+export interface TelegramStatusSnapshot {
     runtime: Record<string, unknown>;
     liveRoster: Record<string, unknown>;
     diagnostics: Record<string, unknown>;
+}
+export interface TelegramStoredRuntimeProjection extends TelegramStatusSnapshot {
+    version: 1;
+    source: "snapshot";
+    writtenAtMs: number;
+}
+export declare function createTelegramStatusSnapshot(state: TelegramBridgeStatusLineState): TelegramStatusSnapshot;
+export interface TelegramRuntimeProjectionScope {
+    path: string;
+    profile: string;
+}
+export interface TelegramRuntimeProjectionStorage {
+    read: (scope: TelegramRuntimeProjectionScope) => unknown;
+    /** The adapter must enforce exact owner plus the supplied physical/logical scope in one transaction. */
+    publish: (scope: TelegramRuntimeProjectionScope, mutate: (current: unknown) => {
+        value: unknown;
+        changed: boolean;
+    }, isCurrent: () => boolean) => boolean;
+}
+export interface TelegramRuntimeProjectionStoreOptions {
+    getPath: () => string;
+    getProfile: () => string | undefined;
+    /** Capture exact owner/context/session authority at submission, never renew it after the queued await. */
+    captureAuthority: () => (() => boolean) | undefined;
+    storage: TelegramRuntimeProjectionStorage;
+    getNowMs?: () => number;
+}
+/** Observational runtime storage only; Workspace, admission, transport, logs and recovery remain with their owners. */
+export declare function createTelegramRuntimeProjectionStore(options: TelegramRuntimeProjectionStoreOptions): {
+    read: () => TelegramStoredRuntimeProjection | undefined;
+    persist: (snapshot: TelegramStatusSnapshot) => Promise<boolean>;
 };
 export declare function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps: {
-    persistSnapshot: () => Promise<void>;
+    persistSnapshot: (isCurrent: () => boolean) => Promise<void>;
     recordError: (error: unknown) => void;
+    captureScope?: () => (() => boolean) | undefined;
     setTimer?: (callback: () => void, ms: number) => {
         unref?: () => void;
-    };
-}): () => void;
+    } | number;
+    clearTimer?: (timer: {
+        unref?: () => void;
+    } | number) => void;
+}): (() => void) & {
+    resume(): void;
+    suspend(): Promise<void>;
+};
 export declare function getTelegramStatusBarProcessingStatus(state: {
     hasActiveTurn: boolean;
     hasPendingDispatch: boolean;
@@ -439,6 +476,4 @@ export declare function getTelegramStatusBarProcessingStatus(state: {
 }): string | undefined;
 export declare function buildTelegramStatusBarText(theme: TelegramStatusBarTheme, state: TelegramStatusBarState): string;
 export declare function buildTelegramBridgeStatusLines(state: TelegramBridgeStatusLineState, options?: TelegramBridgeStatusLineOptions): string[];
-export declare function buildTelegramBridgeDiagnosticStatusLines(state: TelegramBridgeStatusLineState): string[];
-export declare function buildStatusHtml(ctx: TelegramStatusContext, activeModel: TelegramStatusActiveModel | undefined, bridgeStatus?: TelegramBridgeStatusLineState): string;
 export {};

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

@@ -1,8 +1,10 @@
 /**
  * Telegram status rendering helpers
  * Zones: telegram ui, pi agent diagnostics, tui
- * Owns status summaries, redacted runtime diagnostics, and compact connection-failure copy
+ * Owns status summaries, redacted diagnostics, projection lifecycle and compact connection-failure copy
+ * Excludes canonical state, transport admission and filesystem policy
  */
+import { isDeepStrictEqual } from "node:util";
 /** UI copy is allowlisted; raw exception text belongs only in redacted diagnostics. */
 export function formatTelegramConnectionFailure(error) {
     const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
@@ -59,7 +61,7 @@ function truncateTelegramRuntimeEventText(text, maxLength) {
         return text;
     return `${text.slice(0, maxLength).trimEnd()}… [truncated ${text.length - maxLength} chars]`;
 }
-export function redactTelegramRuntimeMessage(message, botToken) {
+function redactTelegramRuntimeMessage(message, botToken) {
     const redacted = botToken
         ? message.split(botToken).join("<redacted-token>")
         : message;
@@ -136,7 +138,7 @@ export function registerTelegramStatusLineProvider(provider, options) {
             registry.delete(options.id);
     };
 }
-export function getTelegramStatusLineProviderResults(ctx) {
+function getTelegramStatusLineProviderResults(ctx) {
     const results = [];
     const registry = getOrCreateTelegramStatusLineProviderRegistry();
     for (const provider of registry.values()) {
@@ -359,7 +361,6 @@ export function createTelegramStatusSnapshot(state) {
             ...(state.localBus ? { localBus: state.localBus } : {}),
             topicTargets: state.topicTargets ?? [],
             reservations: state.threadReservations ?? [],
-            syncObservations: state.topicSyncObservations ?? [],
         },
         diagnostics: {
             pendingDispatch: state.pendingDispatch,
@@ -372,12 +373,71 @@ export function createTelegramStatusSnapshot(state) {
         },
     };
 }
+function isRuntimeProjection(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.version === 1 && record.source === "snapshot" && Number.isSafeInteger(record.writtenAtMs) && record.writtenAtMs >= 0 &&
+        Object.keys(record).every(key => ["version", "source", "writtenAtMs", "runtime", "liveRoster", "diagnostics"].includes(key)) &&
+        ["runtime", "liveRoster", "diagnostics"].every(key => record[key] !== null && typeof record[key] === "object" && !Array.isArray(record[key]));
+}
+/** Observational runtime storage only; Workspace, admission, transport, logs and recovery remain with their owners. */
+export function createTelegramRuntimeProjectionStore(options) {
+    let publicationQueue = Promise.resolve();
+    const { getPath, getProfile: readProfile, captureAuthority } = options;
+    const { read, publish } = options.storage;
+    const getNowMs = options.getNowMs ?? Date.now;
+    const getProfile = () => readProfile() || TELEGRAM_STATUS_DEFAULT_PROFILE_NAME;
+    return {
+        read() {
+            try {
+                const path = getPath(), profile = getProfile(), value = read({ path, profile });
+                return getPath() === path && getProfile() === profile && isRuntimeProjection(value) ? value : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async persist(snapshot) {
+            const path = getPath(), profile = getProfile(), authority = captureAuthority();
+            if (!authority)
+                return false;
+            // Freeze wire content at submission, but do not duplicate the event log in persistent runtime state.
+            const semantic = JSON.parse(JSON.stringify({ version: 1, source: "snapshot", runtime: snapshot.runtime,
+                liveRoster: snapshot.liveRoster, diagnostics: snapshot.diagnostics }));
+            if (!isRuntimeProjection({ ...semantic, writtenAtMs: 0 }))
+                throw new Error("Telegram runtime projection is malformed.");
+            delete semantic.diagnostics.recentRuntimeEvents;
+            const isCurrent = () => getPath() === path && getProfile() === profile && authority() === true;
+            const publication = publicationQueue.then(() => {
+                if (!isCurrent())
+                    return false;
+                return publish({ path, profile }, current => {
+                    if (isRuntimeProjection(current)) {
+                        const { writtenAtMs: _writtenAtMs, ...existing } = current;
+                        if (isDeepStrictEqual(existing, semantic))
+                            return { value: current, changed: false };
+                    }
+                    const writtenAtMs = getNowMs();
+                    if (!Number.isSafeInteger(writtenAtMs) || writtenAtMs < 0)
+                        throw new Error("Telegram runtime projection timestamp is invalid.");
+                    return { value: { ...semantic, writtenAtMs }, changed: true };
+                }, isCurrent) === true;
+            });
+            publicationQueue = publication.then(() => undefined, () => undefined);
+            return publication;
+        },
+    };
+}
 const TELEGRAM_DIAGNOSTICS_SNAPSHOT_COALESCE_MS = 100;
 export function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps) {
     const setTimer = deps.setTimer ?? setTimeout;
+    const clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle));
+    let generation = 0;
+    let enabled = true;
     let timer;
     let persistPromise;
-    let pending = false;
+    let pending;
     const recordError = (error) => {
         try {
             deps.recordError(error);
@@ -386,32 +446,100 @@ export function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps) {
             // Snapshot diagnostics cannot create an unhandled scheduler rejection.
         }
     };
-    const request = () => {
-        if (timer || persistPromise) {
-            pending = true;
+    const cancelTimer = () => {
+        const previous = timer;
+        timer = undefined;
+        if (previous) {
+            try {
+                clearTimer(previous.handle);
+            }
+            catch (error) {
+                recordError(error);
+            }
+        }
+    };
+    const capture = () => {
+        if (!enabled)
+            return undefined;
+        const expectedGeneration = generation;
+        let scope;
+        try {
+            scope = deps.captureScope ? deps.captureScope() : () => true;
+        }
+        catch (error) {
+            recordError(error);
+            return undefined;
+        }
+        if (!scope)
+            return undefined;
+        return () => {
+            if (!enabled || generation !== expectedGeneration)
+                return false;
+            try {
+                return scope();
+            }
+            catch (error) {
+                recordError(error);
+                return false;
+            }
+        };
+    };
+    const arm = () => {
+        if (timer || persistPromise || !pending)
+            return;
+        const authority = pending;
+        if (!authority()) {
+            pending = undefined;
             return;
         }
-        timer = setTimer(() => {
+        const token = {};
+        const handle = setTimer(() => {
+            if (timer?.token !== token)
+                return;
             timer = undefined;
+            const publicationAuthority = pending;
+            pending = undefined;
+            if (!authority() || !publicationAuthority?.())
+                return;
             let tracked;
             tracked = Promise.resolve()
-                .then(deps.persistSnapshot)
+                .then(() => publicationAuthority() ? deps.persistSnapshot(publicationAuthority) : undefined)
                 .catch(recordError)
                 .finally(() => {
                 if (persistPromise !== tracked)
                     return;
                 persistPromise = undefined;
-                if (pending) {
-                    pending = false;
-                    request();
-                }
+                // Only an explicitly captured new request can arm a successor publication.
+                arm();
             });
             persistPromise = tracked;
         }, TELEGRAM_DIAGNOSTICS_SNAPSHOT_COALESCE_MS);
-        if (typeof timer !== "number")
-            timer?.unref?.();
+        timer = { token, handle };
+        if (typeof handle !== "number")
+            handle.unref?.();
+    };
+    const request = () => {
+        const authority = capture();
+        if (!authority)
+            return;
+        pending = authority;
+        arm();
     };
-    return request;
+    return Object.assign(request, {
+        resume() {
+            generation += 1;
+            cancelTimer();
+            pending = undefined;
+            enabled = true;
+        },
+        suspend() {
+            enabled = false;
+            generation += 1;
+            cancelTimer();
+            pending = undefined;
+            return persistPromise ?? Promise.resolve();
+        },
+    });
 }
 export function getTelegramStatusBarProcessingStatus(state) {
     if (state.hasPendingModelSwitch)
@@ -787,15 +915,9 @@ function buildTelegramBridgeCompactStatusLines(state) {
         : state.activeSourceMessageIds?.length
             ? "active"
             : "idle";
-    const diagnosticsProfileName = state.activeProfileName === TELEGRAM_STATUS_DEFAULT_PROFILE_NAME
-        ? undefined
-        : state.activeProfileName;
-    const profileSuffix = diagnosticsProfileName
-        ? `.${diagnosticsProfileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`
-        : "";
     const diagnosticsPaths = state.diagnosticPaths ?? {
-        state: `~/.pi/agent/tmp/telegram/state${profileSuffix}.json`,
-        logs: `~/.pi/agent/tmp/telegram/logs${profileSuffix}.jsonl`,
+        state: "~/.pi/agent/tmp/pi-telegram/state.json",
+        logs: "~/.pi/agent/tmp/pi-telegram/logs.jsonl",
     };
     return [
         "connection:",
@@ -843,7 +965,7 @@ export function buildTelegramBridgeStatusLines(state, options = {}) {
         return buildTelegramBridgeDiagnosticStatusLines(state);
     return buildTelegramBridgeCompactStatusLines(state);
 }
-export function buildTelegramBridgeDiagnosticStatusLines(state) {
+function buildTelegramBridgeDiagnosticStatusLines(state) {
     const controlQueueCount = state.queuedItems.filter((item) => item.queueLane === "control").length;
     const priorityQueueCount = state.queuedItems.filter((item) => item.queueLane === "priority").length;
     const defaultQueueCount = state.queuedItems.filter((item) => item.queueLane === "default").length;
@@ -1002,7 +1124,7 @@ function buildTelegramStatusRoleSuffix(state) {
         return "";
     return ` @${state.busRole}`;
 }
-export function buildStatusHtml(ctx, activeModel, bridgeStatus) {
+function buildStatusHtml(ctx, activeModel, bridgeStatus) {
     const stats = collectUsageStats(ctx);
     const usesSubscription = activeModel
         ? ctx.modelRegistry.isUsingOAuth(activeModel)

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

@@ -94,9 +94,6 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
     workspaceOperationKind?: string;
     getNowMs?: () => number;
 }
-export declare function markTelegramConfigSyncChange<TSyncState extends TelegramSyncState>(state: TSyncState, action: string, options?: {
-    nowMs?: number;
-}): TSyncState;
 export declare function createTelegramPreservedLeaderQuitHandler(deps: {
     instanceId: string;
     topicTargetStore: Pick<TelegramTopicTargetStore, "load" | "list" | "listPendingCleanups" | "detachTargetOwner">;
@@ -109,7 +106,6 @@ export declare function createTelegramPreservedLeaderQuitHandler(deps: {
 export interface TelegramSessionRestartThreadCleanupDeps<TSyncState extends TelegramSyncState> extends Omit<TelegramManualThreadDisconnectDeps<TSyncState>, "stopPolling"> {
     suspendPolling: () => Promise<void>;
 }
-export declare function createTelegramSessionRestartThreadCleanupHandler<TSyncState extends TelegramSyncState>(deps: TelegramSessionRestartThreadCleanupDeps<TSyncState>): () => Promise<string>;
 export interface TelegramThreadDisconnectAssembly {
     disconnect: () => Promise<string>;
     cleanupForSessionRestart: () => Promise<string>;
@@ -141,7 +137,6 @@ export declare function createTelegramStaleTopicApiErrorRecoveryRuntime<TSyncSta
 export declare function settleStaleTelegramTopicExecutionFailure<TSyncState extends TelegramSyncState>(error: unknown, deps: TelegramStaleTopicApiErrorRecoveryDeps<TSyncState>): Promise<boolean>;
 export declare function recoverStaleTelegramTopicApiError<TSyncState extends TelegramSyncState>(apiBody: unknown, error: unknown, deps: TelegramStaleTopicApiErrorRecoveryDeps<TSyncState>): Promise<boolean>;
 export declare function ensureTelegramLeaderThreadBinding(deps: TelegramLeaderThreadSyncDeps): Promise<TelegramOwnTopicProvisionResult | undefined>;
-export declare const TELEGRAM_SYNC_SLICE_TARGET_BINDINGS = "target-bindings";
 export declare const TELEGRAM_SYNC_SLICES: readonly ["bot-identity", "bot-capabilities", "pairing", "allowed-user", "topic-capability", "topic-state", "target-bindings", "reservations", "transport-health"];
 export type TelegramSyncSlice = (typeof TELEGRAM_SYNC_SLICES)[number];
 export type TelegramSyncTrigger = "startup" | "reload" | "topic-lifecycle" | "stale-api-error" | "setup-change" | "pairing-change" | "follower-register" | "follower-prune" | "status-request" | "leader-health-tick" | "ordinary-message" | "ordinary-send";

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

@@ -7,9 +7,10 @@ import { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError } from
 import { getTelegramTargetKey } from "./target.js";
 import * as ThreadReconciler from "./thread-reconciler.js";
 import { TelegramWorkspaceSlotUnavailableError } from "./workspace-slots.js";
+import { normalizeTelegramWorkspacePath } from "./workspace-identity.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
-import { createTelegramCleanupTargetProtection, commitTelegramWorkspaceProvisionBinding, getTelegramTargetFromApiBody, getTelegramThreadOwnerKey, isSameTelegramProcessInstance, isTelegramTopicTargetStaleError, normalizeTelegramWorkspacePath, provisionOwnBusTopic, } from "./threads.js";
-export function markTelegramConfigSyncChange(state, action, options) {
+import { createTelegramCleanupTargetProtection, commitTelegramWorkspaceProvisionBinding, getTelegramTargetFromApiBody, getTelegramThreadOwnerKey, isSameTelegramProcessInstance, isTelegramTopicTargetStaleError, provisionOwnBusTopic, } from "./threads.js";
+function markTelegramConfigSyncChange(state, action, options) {
     const nowMs = options?.nowMs ?? Date.now();
     let nextState = markTelegramSyncSliceFresh(state, "pairing", {
         nowMs,
@@ -61,7 +62,7 @@ export function createTelegramPreservedLeaderQuitHandler(deps) {
         };
     };
 }
-export function createTelegramSessionRestartThreadCleanupHandler(deps) {
+function createTelegramSessionRestartThreadCleanupHandler(deps) {
     return createTelegramManualThreadDisconnectHandler({
         ...deps,
         workspaceOperationKind: "workspace.cleanup-session-restart",
@@ -655,7 +656,7 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
         deps.topicTargetStore.releaseWorkspaceClaim(deps.instanceId);
     }
 }
-export const TELEGRAM_SYNC_SLICE_TARGET_BINDINGS = "target-bindings";
+const TELEGRAM_SYNC_SLICE_TARGET_BINDINGS = "target-bindings";
 export const TELEGRAM_SYNC_SLICES = [
     "bot-identity",
     "bot-capabilities",

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

@@ -5,7 +5,7 @@
  * Wraps bot API calls, file uploads/downloads (including voice messages),
  * multipart sending, runtime transport binding, and Telegram temp-file lifecycle.
  */
-export declare const TELEGRAM_API_BASE = "https://api.telegram.org";
+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;
 export type TelegramNetworkFamilyPolicy = "auto" | "ipv4" | "ipv6" | "ipv4-fallback";
@@ -415,6 +415,8 @@ export interface TelegramBridgeApiRuntimeDeps {
     tempDir: string;
     maxFileSizeBytes: number;
     tempFileMaxAgeMs: number;
+    /** Bot `@username` (or numeric id) naming private-chat attachments. */
+    getBotScope?: () => string | undefined;
     recordRuntimeEvent: (kind: "api" | "multipart" | "download", error: unknown, details?: Record<string, unknown>) => void;
     now?: () => number;
     chatActionMinIntervalMs?: number;
@@ -423,7 +425,7 @@ export interface TelegramBridgeApiRuntimeDeps {
 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>;
-    downloadFile: (fileId: string, suggestedName: string) => Promise<string>;
+    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 {
@@ -462,6 +464,12 @@ export interface TelegramBridgeApiRuntime {
     deleteMessage: (chatId: number, messageId: number) => Promise<void>;
     prepareTempDir: () => Promise<number>;
 }
+/** Names follow `<kind>-<scope>-<messageId>[-<index>][-<name>|.<ext>]`. */
+/**
+ * `scope` is the bot `@username` (id fallback) in a private chat and the public chat `@username` (id fallback) elsewhere.
+ * A negative chat id loses its sign, so the name never contains two adjacent dashes.
+ */
+export declare function createTelegramAttachmentFileName(source: TelegramAttachmentSource, generatedName: string, botScope?: string): string;
 export declare class TelegramApiCommitUnknownError extends Error {
     readonly kind: "commit-unknown";
     readonly method: string;
@@ -507,7 +515,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>;
 export declare function answerTelegramCallbackQuery(botToken: string | undefined, callbackQueryId: string, text?: string, options?: TelegramAnswerCallbackQueryOptions): Promise<void>;
-export declare function deleteTelegramMessage(botToken: string | undefined, chatId: number, messageId: number): Promise<void>;
 export declare function createTelegramChatActionSender<TAction extends string>(sendChatAction: (chatId: number, action: TAction, options?: {
     message_thread_id?: number;
 }) => Promise<unknown>, action: TAction): (chatId: number, options?: {
@@ -530,6 +537,7 @@ export type TelegramWorkspaceThreadDeletionTransport = (authorize: () => {
 }) => Promise<void>;
 export declare function createDefaultTelegramBridgeApiRuntime(deps: {
     getBotToken: () => string | undefined;
+    getBotScope?: () => string | undefined;
     recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
     captureRequestErrorHandler?: TelegramBridgeApiRuntimeDeps["captureRequestErrorHandler"];
     targetActivity?: TelegramApiTargetActivityRuntime;

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

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

package/node_modules/@llblab/pi-telegram/dist/lib/thread-cleanup-manager.d.ts

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