@llblab/pi-telegram 0.46.0 → 0.48.0

package/dist/lib/logging.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Telegram diagnostics logs
+ * Zones: telegram diagnostics, filesystem, session observability
+ * Owns bounded JSONL runtime evidence files, previous-log preservation, and profile-aware log paths without becoming routing state
+ */
+import * as Status from "./status.ts";
+export type TelegramLogPathInput = string | (() => string);
+export interface TelegramRuntimeJsonlEvent {
+    at: number;
+    category: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface TelegramRuntimeJsonlLogOptions {
+    path?: TelegramLogPathInput;
+    previousPath?: TelegramLogPathInput;
+    maxBytes?: number;
+    getNowMs?: () => number;
+    canReset?: () => boolean;
+    commitReset?: (commit: () => void) => boolean;
+}
+export interface TelegramRuntimeJsonlLog {
+    getPath: () => string;
+    reset: (reason: string, scope?: Record<string, unknown>) => void;
+    resetIfScopeChanged: (scopeKey: string, reason: string, scope?: Record<string, unknown>) => void;
+    record: (event: TelegramRuntimeJsonlEvent) => void;
+}
+export declare function getTelegramRuntimeLogPath(agentDir?: string, profileName?: string): string;
+export declare function getTelegramPreviousRuntimeLogPath(agentDir?: string, profileName?: string): string;
+export declare function createTelegramRuntimeJsonlLog(options?: TelegramRuntimeJsonlLogOptions): TelegramRuntimeJsonlLog;
+export interface TelegramRuntimeDiagnosticsRuntime<TContext> {
+    events: Status.TelegramRuntimeEventRecorder;
+    recordRuntimeEvent(category: string, error: unknown, details?: Record<string, unknown>): void;
+    bindStorage(ports: {
+        getBotToken(): string | undefined;
+        getProfileName(): string | undefined;
+        canReset(): boolean;
+        commitReset(commit: () => void): boolean;
+    }): void;
+    bindStatus(ports: {
+        instanceId: string;
+        updateStatus(ctx: TContext, error?: string): void;
+        getStatusState(): Status.TelegramBridgeStatusLineState;
+        persistSnapshot(snapshot: ReturnType<typeof Status.createTelegramStatusSnapshot>): Promise<void>;
+    }): void;
+    updateStatus(ctx: TContext, error?: string): void;
+    getStatusLines(options?: Status.TelegramBridgeStatusLineOptions): string[];
+    scheduleSnapshotPersist(): void;
+}
+export declare function createTelegramRuntimeDiagnosticsRuntime<TContext>(): TelegramRuntimeDiagnosticsRuntime<TContext>;

package/dist/lib/logging.js

@@ -0,0 +1,274 @@
+/**
+ * Telegram diagnostics logs
+ * Zones: telegram diagnostics, filesystem, session observability
+ * Owns bounded JSONL runtime evidence files, previous-log preservation, and profile-aware log paths without becoming routing state
+ */
+import { copyFileSync, existsSync, mkdirSync, statSync, writeFileSync, appendFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { resolveAgentDir, resolveTelegramProfileTempFilePath, } from "./paths.js";
+import { withTelegramFileTransaction } from "./locks.js";
+import * as Status from "./status.js";
+const DEFAULT_MAX_LOG_BYTES = 5 * 1024 * 1024;
+export function getTelegramRuntimeLogPath(agentDir = resolveAgentDir(), profileName) {
+    return resolveTelegramProfileTempFilePath("logs", "jsonl", agentDir, profileName);
+}
+export function getTelegramPreviousRuntimeLogPath(agentDir = resolveAgentDir(), profileName) {
+    return resolveTelegramProfileTempFilePath("logs", "_prev.jsonl", agentDir, profileName);
+}
+function safeJsonLine(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (item instanceof Error)
+            return item.message;
+        if (typeof item === "bigint")
+            return item.toString();
+        if (typeof item === "function" || typeof item === "symbol")
+            return undefined;
+        return item;
+    });
+}
+export function createTelegramRuntimeJsonlLog(options = {}) {
+    const resolvePath = () => typeof options.path === "function"
+        ? options.path()
+        : (options.path ?? getTelegramRuntimeLogPath());
+    const resolvePreviousPath = () => {
+        if (typeof options.previousPath === "function")
+            return options.previousPath();
+        if (options.previousPath)
+            return options.previousPath;
+        return resolvePath().replace(/\.jsonl$/u, "._prev.jsonl");
+    };
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_LOG_BYTES;
+    const getNowMs = options.getNowMs ?? Date.now;
+    const scopeKeys = new Map();
+    let pending = Promise.resolve();
+    let appendScheduled = false;
+    let queuedAppends = [];
+    const ensureParent = (path) => {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    };
+    const preserveCurrentLog = (path, previousPath) => {
+        if (!existsSync(path))
+            return;
+        mkdirSync(dirname(previousPath), { recursive: true, mode: 0o700 });
+        copyFileSync(path, previousPath);
+    };
+    const writeResetLocked = (path, previousPath, reason, scope) => {
+        ensureParent(path);
+        preserveCurrentLog(path, previousPath);
+        writeFileSync(path, safeJsonLine({
+            at: getNowMs(),
+            kind: "reset",
+            reason,
+            scope,
+            previousPath,
+        }) + "\n", { mode: 0o600 });
+    };
+    const writeReset = (reason, scope) => {
+        if (options.canReset && !options.canReset())
+            return false;
+        const path = resolvePath();
+        let didReset = false;
+        withTelegramFileTransaction(`${path}.transaction`, () => {
+            const commit = () => {
+                writeResetLocked(path, resolvePreviousPath(), reason, scope);
+                didReset = true;
+            };
+            if (options.commitReset) {
+                options.commitReset(commit);
+            }
+            else {
+                commit();
+            }
+        });
+        return didReset;
+    };
+    const appendLine = (line) => {
+        queuedAppends.push({
+            path: resolvePath(),
+            previousPath: resolvePreviousPath(),
+            line,
+        });
+        if (appendScheduled)
+            return;
+        appendScheduled = true;
+        pending = pending
+            .then(() => {
+            appendScheduled = false;
+            const batch = queuedAppends;
+            queuedAppends = [];
+            const groups = new Map();
+            for (const entry of batch) {
+                const key = `${entry.path}\u0000${entry.previousPath}`;
+                const group = groups.get(key);
+                if (group)
+                    group.lines.push(entry.line);
+                else
+                    groups.set(key, { ...entry, lines: [entry.line] });
+            }
+            for (const group of groups.values()) {
+                try {
+                    ensureParent(group.path);
+                    withTelegramFileTransaction(`${group.path}.transaction`, () => {
+                        let currentSize = existsSync(group.path)
+                            ? statSync(group.path).size
+                            : 0;
+                        let chunk = "";
+                        let chunkBytes = 0;
+                        const flushChunk = () => {
+                            if (!chunk)
+                                return;
+                            appendFileSync(group.path, chunk, { mode: 0o600 });
+                            currentSize += chunkBytes;
+                            chunk = "";
+                            chunkBytes = 0;
+                        };
+                        const rotate = () => {
+                            if (options.canReset && !options.canReset())
+                                return false;
+                            let rotated = false;
+                            const commit = () => {
+                                writeResetLocked(group.path, group.previousPath, "max-bytes", { maxBytes });
+                                rotated = true;
+                            };
+                            if (options.commitReset)
+                                options.commitReset(commit);
+                            else
+                                commit();
+                            if (rotated)
+                                currentSize = statSync(group.path).size;
+                            return rotated;
+                        };
+                        for (const line of group.lines) {
+                            const lineBytes = Buffer.byteLength(line);
+                            if (currentSize + chunkBytes > 0 &&
+                                currentSize + chunkBytes + lineBytes > maxBytes) {
+                                flushChunk();
+                                rotate();
+                            }
+                            chunk += line;
+                            chunkBytes += lineBytes;
+                        }
+                        flushChunk();
+                    });
+                }
+                catch {
+                    // Diagnostics failures for one profile must not drop other groups.
+                }
+            }
+        })
+            .catch(() => undefined);
+    };
+    return {
+        getPath: resolvePath,
+        reset(reason, scope) {
+            const path = resolvePath();
+            try {
+                if (writeReset(reason, scope)) {
+                    scopeKeys.set(path, scope ? safeJsonLine(scope) : undefined);
+                }
+            }
+            catch {
+                // Diagnostics must never break Telegram runtime behavior.
+            }
+        },
+        resetIfScopeChanged(nextScopeKey, reason, scope) {
+            const path = resolvePath();
+            if (scopeKeys.get(path) === nextScopeKey)
+                return;
+            try {
+                if (writeReset(reason, scope))
+                    scopeKeys.set(path, nextScopeKey);
+            }
+            catch {
+                // Diagnostics must never break Telegram runtime behavior.
+            }
+        },
+        record(event) {
+            try {
+                appendLine(safeJsonLine({ kind: "event", ...event }) + "\n");
+            }
+            catch {
+                // Diagnostics must never break Telegram runtime behavior.
+            }
+        },
+    };
+}
+export function createTelegramRuntimeDiagnosticsRuntime() {
+    let getBotToken = () => undefined;
+    let getProfileName = () => undefined;
+    let canReset = () => false;
+    let commitReset = (_commit) => false;
+    let statusPorts;
+    let requestSnapshotPersist = () => { };
+    const events = Status.createTelegramRuntimeEventRecorder({
+        getBotToken: () => getBotToken(),
+    });
+    const jsonl = createTelegramRuntimeJsonlLog({
+        path: () => getTelegramRuntimeLogPath(undefined, getProfileName()),
+        previousPath: () => getTelegramPreviousRuntimeLogPath(undefined, getProfileName()),
+        canReset: () => canReset(),
+        commitReset: (commit) => commitReset(commit),
+    });
+    const recordRuntimeEvent = function (category, error, details) {
+        events.record(category, error, details);
+        const latestEvent = events.getEvents().at(-1);
+        if (latestEvent)
+            jsonl.record(latestEvent);
+        requestSnapshotPersist();
+    };
+    const persistCurrentSnapshot = async () => {
+        if (!statusPorts)
+            return;
+        await statusPorts.persistSnapshot(Status.createTelegramStatusSnapshot(statusPorts.getStatusState()));
+    };
+    const updateRuntimeLogScope = function (reason) {
+        if (!statusPorts)
+            return;
+        const scope = Status.createTelegramRuntimeLogScope({
+            state: statusPorts.getStatusState(),
+            instanceId: statusPorts.instanceId,
+        });
+        jsonl.resetIfScopeChanged(JSON.stringify(scope), reason, scope);
+    };
+    return {
+        events,
+        recordRuntimeEvent,
+        bindStorage(ports) {
+            getBotToken = ports.getBotToken;
+            getProfileName = ports.getProfileName;
+            canReset = ports.canReset;
+            commitReset = ports.commitReset;
+        },
+        bindStatus(ports) {
+            statusPorts = ports;
+            requestSnapshotPersist =
+                Status.createTelegramRuntimeDiagnosticsSnapshotScheduler({
+                    persistSnapshot: persistCurrentSnapshot,
+                    recordError(error) {
+                        events.record("telegram", error, {
+                            phase: "runtime-diagnostics-snapshot-persist",
+                        });
+                    },
+                });
+        },
+        updateStatus(ctx, error) {
+            if (!statusPorts)
+                return;
+            statusPorts.updateStatus(ctx, error);
+            updateRuntimeLogScope("status-scope-change");
+        },
+        getStatusLines(options) {
+            if (!statusPorts)
+                return [];
+            void persistCurrentSnapshot().catch((error) => {
+                recordRuntimeEvent("telegram", error, {
+                    phase: "status-snapshot-persist",
+                });
+            });
+            return Status.buildTelegramBridgeStatusLines(statusPorts.getStatusState(), options);
+        },
+        scheduleSnapshotPersist() {
+            requestSnapshotPersist();
+        },
+    };
+}

package/dist/lib/media.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Telegram media and text extraction helpers
+ * Zones: telegram inbound, media groups, filesystem paths
+ * Normalizes inbound Telegram messages into reusable file, text, id, history, and media-group metadata
+ */
+export interface TelegramPhotoSize {
+    file_id: string;
+    file_size?: number;
+}
+export interface TelegramDocument {
+    file_id: string;
+    file_name?: string;
+    mime_type?: string;
+}
+export type TelegramVideo = TelegramDocument;
+export type TelegramAudio = TelegramDocument;
+export type TelegramAnimation = TelegramDocument;
+export interface TelegramVoice {
+    file_id: string;
+    mime_type?: string;
+}
+export interface TelegramRichMessage {
+    blocks?: unknown[];
+}
+export interface TelegramMessageUser {
+    id?: number;
+    is_bot?: boolean;
+    first_name?: string;
+    last_name?: string;
+    username?: string;
+}
+export interface TelegramMessageForwardOrigin {
+    type?: string;
+    sender_user?: TelegramMessageUser;
+    sender_user_name?: string;
+    sender_chat?: {
+        title?: string;
+        username?: string;
+        id?: number;
+    };
+    chat?: {
+        title?: string;
+        username?: string;
+        id?: number;
+    };
+    author_signature?: string;
+}
+export interface TelegramReplyToMessage {
+    message_id?: number;
+    from?: TelegramMessageUser;
+    text?: string;
+    caption?: string;
+    rich_message?: TelegramRichMessage;
+    photo?: TelegramPhotoSize[];
+    document?: TelegramDocument;
+    video?: TelegramVideo;
+    audio?: TelegramAudio;
+    voice?: TelegramVoice;
+    animation?: TelegramAnimation;
+    sticker?: TelegramSticker;
+}
+export interface TelegramSticker {
+    file_id: string;
+}
+export interface TelegramMediaMessage {
+    message_id: number;
+    from?: TelegramMessageUser;
+    forward_origin?: TelegramMessageForwardOrigin;
+    forward_from?: TelegramMessageUser;
+    forward_sender_name?: string;
+    text?: string;
+    caption?: string;
+    rich_message?: TelegramRichMessage;
+    reply_to_message?: TelegramReplyToMessage;
+    media_group_id?: string;
+    photo?: TelegramPhotoSize[];
+    document?: TelegramDocument;
+    video?: TelegramVideo;
+    audio?: TelegramAudio;
+    voice?: TelegramVoice;
+    animation?: TelegramAnimation;
+    sticker?: TelegramSticker;
+}
+export interface TelegramMediaGroupMessage {
+    message_id: number;
+    chat: {
+        id: number;
+    };
+    message_thread_id?: number;
+    media_group_id?: string;
+}
+export interface TelegramMediaGroupState<TMessage, TContext = unknown> {
+    messages: TMessage[];
+    context?: TContext;
+    flushTimer?: ReturnType<typeof setTimeout>;
+    dispatching?: boolean;
+    dispatchPromise?: Promise<void>;
+    dispatchNow?: () => Promise<void>;
+    suspended?: boolean;
+    reschedule?: () => void;
+}
+export interface TelegramMediaGroupController<TMessage extends TelegramMediaGroupMessage, TContext = unknown> {
+    queueMessage: (options: {
+        message: TMessage;
+        context?: TContext;
+        dispatchMessages: (messages: TMessage[], ctx?: TContext) => unknown | Promise<unknown>;
+    }) => boolean;
+    removeMessages: (messageIds: number[]) => number;
+    flushMessage: (messageId: number) => Promise<boolean>;
+    suspend: () => void;
+    resume: (context: TContext) => void;
+    clear: () => void;
+}
+export interface TelegramMediaGroupDispatchRuntimeDeps<TMessage extends TelegramMediaGroupMessage, TContext> {
+    mediaGroups: TelegramMediaGroupController<TMessage, TContext>;
+    dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
+    onDeferredMessage?: (message: TMessage) => void;
+}
+export interface TelegramMediaGroupDispatchRuntime<TMessage extends TelegramMediaGroupMessage, TContext> {
+    handleMessage: (message: TMessage, ctx: TContext) => Promise<void>;
+}
+export interface TelegramMediaGroupControllerOptions {
+    debounceMs?: number;
+    setTimer?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+export type TelegramAttachmentKind = "photo" | "document" | "video" | "audio" | "voice" | "animation" | "sticker";
+export interface TelegramFileInfo {
+    file_id: string;
+    fileName: string;
+    mimeType?: string;
+    kind: TelegramAttachmentKind;
+    isImage: boolean;
+}
+export interface DownloadedTelegramFile {
+    path: string;
+    fileName?: string;
+    isImage?: boolean;
+    mimeType?: string;
+    kind?: TelegramAttachmentKind;
+}
+export interface DownloadedTelegramMessageFile {
+    path: string;
+    fileName: string;
+    isImage: boolean;
+    mimeType?: string;
+    kind?: TelegramAttachmentKind;
+}
+export interface DownloadTelegramMessageFilesDeps {
+    downloadFile: (fileId: string, fileName: string) => Promise<string>;
+}
+export declare function guessExtensionFromMime(mimeType: string | undefined, fallback: string): string;
+export declare function guessMediaType(path: string): string | undefined;
+export declare function extractTelegramMessageText(message: TelegramMediaMessage): string;
+export declare function extractTelegramForwardContextText(message: TelegramMediaMessage, allowedUserId?: number): string;
+export declare function extractTelegramReplyContextText(message: TelegramMediaMessage): string;
+export declare function buildTelegramReplyContextBlock(message: TelegramMediaMessage, replyFiles?: Pick<DownloadedTelegramFile, "path">[], replyOutputs?: readonly string[]): string;
+export declare function appendTelegramReplyContext(text: string, replyContext: string): string;
+export declare function extractTelegramMessagePromptText(message: TelegramMediaMessage): string;
+export declare function extractTelegramMessagesText(messages: TelegramMediaMessage[]): string;
+export declare function extractTelegramMessagesPromptText(messages: TelegramMediaMessage[]): string;
+export declare function extractFirstTelegramMessageText(messages: TelegramMediaMessage[]): string;
+export declare function hasTelegramMessagePromptContent(message: TelegramMediaMessage): boolean;
+export declare function hasTelegramMessagesPromptContent(messages: TelegramMediaMessage[]): boolean;
+export declare function collectTelegramMessageIds(messages: TelegramMediaMessage[]): number[];
+export declare function getTelegramMediaGroupKey(message: TelegramMediaGroupMessage): string | undefined;
+export declare function removePendingTelegramMediaGroupMessages<TMessage extends TelegramMediaGroupMessage>(groups: Map<string, TelegramMediaGroupState<TMessage, unknown>>, messageIds: number[], clearTimer: (timer: ReturnType<typeof setTimeout>) => void): number;
+export declare function queueTelegramMediaGroupMessage<TMessage extends TelegramMediaGroupMessage, TContext = unknown>(options: {
+    message: TMessage;
+    context?: TContext;
+    groups: Map<string, TelegramMediaGroupState<TMessage, TContext>>;
+    debounceMs: number;
+    setTimer: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
+    dispatchMessages: (messages: TMessage[], ctx?: TContext) => unknown | Promise<unknown>;
+}): boolean;
+export declare function createTelegramMediaGroupController<TMessage extends TelegramMediaGroupMessage, TContext = unknown>(options?: TelegramMediaGroupControllerOptions): TelegramMediaGroupController<TMessage, TContext>;
+export declare function createTelegramMediaGroupDispatchRuntime<TMessage extends TelegramMediaGroupMessage, TContext>(deps: TelegramMediaGroupDispatchRuntimeDeps<TMessage, TContext>): TelegramMediaGroupDispatchRuntime<TMessage, TContext>;
+export declare function formatTelegramHistoryText(rawText: string, files: DownloadedTelegramFile[], handlerOutputs?: string[]): string;
+export declare function downloadTelegramMessageFiles(messages: TelegramMediaMessage[], deps: DownloadTelegramMessageFilesDeps): Promise<DownloadedTelegramMessageFile[]>;
+export declare function collectTelegramFileInfos(messages: TelegramMediaMessage[]): TelegramFileInfo[];