@llblab/pi-telegram 0.51.5 → 0.52.0

package/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/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/dist/lib/status.d.ts

@@ -1,8 +1,11 @@
 /**
  * Telegram status rendering helpers
  * Zones: telegram ui, pi agent diagnostics, tui
- * Builds usage, cost, and context summaries for the interactive Telegram status view
+ * 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;
 export type TelegramStatusQueueLane = "control" | "priority" | "default";
 export interface TelegramUsageStats {
     totalInput: number;
@@ -376,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;
@@ -392,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[];
@@ -416,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;
@@ -437,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/dist/lib/status.js

@@ -1,8 +1,40 @@
 /**
  * Telegram status rendering helpers
  * Zones: telegram ui, pi agent diagnostics, tui
- * Builds usage, cost, and context summaries for the interactive Telegram status view
+ * 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 : "";
+    const status = error && typeof error === "object" && "status" in error ? error.status : undefined;
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    if (status === 401)
+        return "Telegram token rejected. Run /telegram-setup.";
+    if (status === 403)
+        return "Telegram access denied. Check /telegram-status --debug.";
+    if ((typeof code === "string" && ["ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "ECONNRESET"].includes(code)) ||
+        /network unavailable|fetch failed/i.test(message)) {
+        return "Telegram network unavailable. Retry /telegram-connect.";
+    }
+    if (/Workspace slots?.*(?:unavailable|exhausted)|no free.*slot/i.test(message)) {
+        return "No Telegram slot available. Check /telegram-status --debug.";
+    }
+    if (code === "incompatible-protocol" || /protocol.*(?:incompatible|mismatch)|incompatible.*protocol/i.test(message)) {
+        return "Telegram instances are incompatible. Update them together.";
+    }
+    if (/unsupported.*(?:journal|version)|(?:journal|version).*unsupported/i.test(message)) {
+        return "Telegram state version unsupported. Use a compatible runtime.";
+    }
+    if (/follower registration failed|active in another Pi instance/i.test(message)) {
+        return "Telegram leader is active but unavailable. Check /telegram-status --debug.";
+    }
+    if (/unfinished Thread creation does not match/i.test(message)) {
+        return "Telegram Thread creation is unresolved. Check /telegram-status --debug.";
+    }
+    return "Telegram connection failed. Check /telegram-status --debug.";
+}
 const TELEGRAM_STATUS_DEFAULT_PROFILE_NAME = "default";
 const TELEGRAM_STATUS_LINE_PROVIDER_REGISTRY_KEY = "__piTelegramStatusLineProviders__";
 const MAX_RECENT_TELEGRAM_RUNTIME_EVENTS = 10;
@@ -29,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;
@@ -106,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()) {
@@ -329,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,
@@ -342,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);
@@ -356,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)
@@ -757,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:",
@@ -813,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;
@@ -972,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/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/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",
@@ -459,6 +460,7 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
             ? deps.topicTargetStore.getWorkspaceBinding(workspaceIdentity.cwd, workspaceIdentity.instanceSlot, workspaceIdentity.sessionId)
             : undefined;
         const legacyWorkspaceBinding = workspaceIdentity?.instanceSlot === "a" &&
+            deps.sessionId === undefined &&
             !persistedWorkspaceBinding &&
             typeof legacyLeaderRecord?.target.threadId === "number"
             ? {
@@ -553,10 +555,9 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
             return (record.instanceId === deps.instanceId &&
                 (record.status === "active" || record.status === "starting"));
         });
-        // Short-circuit: when the instance already has an active thread and we are not
-        // force-freshing, reuse it without re-provisioning. A thread belongs to the
-        // live instance binding, not to one transient Pi session lifecycle.
-        if (!deps.forceFreshUnnamed && priorTargets.length > 0) {
+        // 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) {
             const record = priorTargets[0];
             deps.recordEvent("telegram", "Leader thread preserved after session lifecycle change", {
                 phase: "leader-thread-reused",
@@ -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/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;