@poolzin/pool-bot 2026.3.25 → 2026.3.27

package/dist/telegram/bot-message-context.session.js

@@ -0,0 +1,207 @@
+import { normalizeCommandBody } from "../../../src/auto-reply/commands-registry.js";
+import { formatInboundEnvelope, resolveEnvelopeFormatOptions, } from "../../../src/auto-reply/envelope.js";
+import { buildPendingHistoryContextFromMap, } from "../../../src/auto-reply/reply/history.js";
+import { finalizeInboundContext } from "../../../src/auto-reply/reply/inbound-context.js";
+import { toLocationContext } from "../../../src/channels/location.js";
+import { recordInboundSession } from "../../../src/channels/session.js";
+import { readSessionUpdatedAt, resolveStorePath } from "../../../src/config/sessions.js";
+import { logVerbose, shouldLogVerbose } from "../../../src/globals.js";
+import { resolveInboundLastRouteSessionKey } from "../../../src/routing/resolve-route.js";
+import { resolvePinnedMainDmOwnerFromAllowlist } from "../../../src/security/dm-policy-shared.js";
+import { normalizeAllowFrom } from "./bot-access.js";
+import { buildGroupLabel, buildSenderLabel, buildSenderName, buildTelegramGroupFrom, describeReplyTarget, normalizeForwardedContext, } from "./bot/helpers.js";
+import { resolveTelegramGroupPromptSettings } from "./group-config-helpers.js";
+export async function buildTelegramInboundContextPayload(params) {
+    const { cfg, primaryCtx, msg, allMedia, replyMedia, isGroup, isForum, chatId, senderId, senderUsername, resolvedThreadId, dmThreadId, threadSpec, route, rawBody, bodyText, historyKey, historyLimit, groupHistories, groupConfig, topicConfig, stickerCacheHit, effectiveWasMentioned, commandAuthorized, locationData, options, dmAllowFrom, } = params;
+    const replyTarget = describeReplyTarget(msg);
+    const forwardOrigin = normalizeForwardedContext(msg);
+    const replyForwardAnnotation = replyTarget?.forwardedFrom
+        ? `[Forwarded from ${replyTarget.forwardedFrom.from}${replyTarget.forwardedFrom.date
+            ? ` at ${new Date(replyTarget.forwardedFrom.date * 1000).toISOString()}`
+            : ""}]\n`
+        : "";
+    const replySuffix = replyTarget
+        ? replyTarget.kind === "quote"
+            ? `\n\n[Quoting ${replyTarget.sender}${replyTarget.id ? ` id:${replyTarget.id}` : ""}]\n${replyForwardAnnotation}"${replyTarget.body}"\n[/Quoting]`
+            : `\n\n[Replying to ${replyTarget.sender}${replyTarget.id ? ` id:${replyTarget.id}` : ""}]\n${replyForwardAnnotation}${replyTarget.body}\n[/Replying]`
+        : "";
+    const forwardPrefix = forwardOrigin
+        ? `[Forwarded from ${forwardOrigin.from}${forwardOrigin.date ? ` at ${new Date(forwardOrigin.date * 1000).toISOString()}` : ""}]\n`
+        : "";
+    const groupLabel = isGroup ? buildGroupLabel(msg, chatId, resolvedThreadId) : undefined;
+    const senderName = buildSenderName(msg);
+    const conversationLabel = isGroup
+        ? (groupLabel ?? `group:${chatId}`)
+        : buildSenderLabel(msg, senderId || chatId);
+    const storePath = resolveStorePath(cfg.session?.store, {
+        agentId: route.agentId,
+    });
+    const envelopeOptions = resolveEnvelopeFormatOptions(cfg);
+    const previousTimestamp = readSessionUpdatedAt({
+        storePath,
+        sessionKey: route.sessionKey,
+    });
+    const body = formatInboundEnvelope({
+        channel: "Telegram",
+        from: conversationLabel,
+        timestamp: msg.date ? msg.date * 1000 : undefined,
+        body: `${forwardPrefix}${bodyText}${replySuffix}`,
+        chatType: isGroup ? "group" : "direct",
+        sender: {
+            name: senderName,
+            username: senderUsername || undefined,
+            id: senderId || undefined,
+        },
+        previousTimestamp,
+        envelope: envelopeOptions,
+    });
+    let combinedBody = body;
+    if (isGroup && historyKey && historyLimit > 0) {
+        combinedBody = buildPendingHistoryContextFromMap({
+            historyMap: groupHistories,
+            historyKey,
+            limit: historyLimit,
+            currentMessage: combinedBody,
+            formatEntry: (entry) => formatInboundEnvelope({
+                channel: "Telegram",
+                from: groupLabel ?? `group:${chatId}`,
+                timestamp: entry.timestamp,
+                body: `${entry.body} [id:${entry.messageId ?? "unknown"} chat:${chatId}]`,
+                chatType: "group",
+                senderLabel: entry.sender,
+                envelope: envelopeOptions,
+            }),
+        });
+    }
+    const { skillFilter, groupSystemPrompt } = resolveTelegramGroupPromptSettings({
+        groupConfig,
+        topicConfig,
+    });
+    const commandBody = normalizeCommandBody(rawBody, {
+        botUsername: primaryCtx.me?.username?.toLowerCase(),
+    });
+    const inboundHistory = isGroup && historyKey && historyLimit > 0
+        ? (groupHistories.get(historyKey) ?? []).map((entry) => ({
+            sender: entry.sender,
+            body: entry.body,
+            timestamp: entry.timestamp,
+        }))
+        : undefined;
+    const currentMediaForContext = stickerCacheHit ? [] : allMedia;
+    const contextMedia = [...currentMediaForContext, ...replyMedia];
+    const ctxPayload = finalizeInboundContext({
+        Body: combinedBody,
+        BodyForAgent: bodyText,
+        InboundHistory: inboundHistory,
+        RawBody: rawBody,
+        CommandBody: commandBody,
+        From: isGroup ? buildTelegramGroupFrom(chatId, resolvedThreadId) : `telegram:${chatId}`,
+        To: `telegram:${chatId}`,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: isGroup ? "group" : "direct",
+        ConversationLabel: conversationLabel,
+        GroupSubject: isGroup ? (msg.chat.title ?? undefined) : undefined,
+        GroupSystemPrompt: isGroup || (!isGroup && groupConfig) ? groupSystemPrompt : undefined,
+        SenderName: senderName,
+        SenderId: senderId || undefined,
+        SenderUsername: senderUsername || undefined,
+        Provider: "telegram",
+        Surface: "telegram",
+        BotUsername: primaryCtx.me?.username ?? undefined,
+        MessageSid: options?.messageIdOverride ?? String(msg.message_id),
+        ReplyToId: replyTarget?.id,
+        ReplyToBody: replyTarget?.body,
+        ReplyToSender: replyTarget?.sender,
+        ReplyToIsQuote: replyTarget?.kind === "quote" ? true : undefined,
+        ReplyToForwardedFrom: replyTarget?.forwardedFrom?.from,
+        ReplyToForwardedFromType: replyTarget?.forwardedFrom?.fromType,
+        ReplyToForwardedFromId: replyTarget?.forwardedFrom?.fromId,
+        ReplyToForwardedFromUsername: replyTarget?.forwardedFrom?.fromUsername,
+        ReplyToForwardedFromTitle: replyTarget?.forwardedFrom?.fromTitle,
+        ReplyToForwardedDate: replyTarget?.forwardedFrom?.date
+            ? replyTarget.forwardedFrom.date * 1000
+            : undefined,
+        ForwardedFrom: forwardOrigin?.from,
+        ForwardedFromType: forwardOrigin?.fromType,
+        ForwardedFromId: forwardOrigin?.fromId,
+        ForwardedFromUsername: forwardOrigin?.fromUsername,
+        ForwardedFromTitle: forwardOrigin?.fromTitle,
+        ForwardedFromSignature: forwardOrigin?.fromSignature,
+        ForwardedFromChatType: forwardOrigin?.fromChatType,
+        ForwardedFromMessageId: forwardOrigin?.fromMessageId,
+        ForwardedDate: forwardOrigin?.date ? forwardOrigin.date * 1000 : undefined,
+        Timestamp: msg.date ? msg.date * 1000 : undefined,
+        WasMentioned: isGroup ? effectiveWasMentioned : undefined,
+        MediaPath: contextMedia.length > 0 ? contextMedia[0]?.path : undefined,
+        MediaType: contextMedia.length > 0 ? contextMedia[0]?.contentType : undefined,
+        MediaUrl: contextMedia.length > 0 ? contextMedia[0]?.path : undefined,
+        MediaPaths: contextMedia.length > 0 ? contextMedia.map((m) => m.path) : undefined,
+        MediaUrls: contextMedia.length > 0 ? contextMedia.map((m) => m.path) : undefined,
+        MediaTypes: contextMedia.length > 0
+            ? contextMedia.map((m) => m.contentType).filter(Boolean)
+            : undefined,
+        Sticker: allMedia[0]?.stickerMetadata,
+        StickerMediaIncluded: allMedia[0]?.stickerMetadata ? !stickerCacheHit : undefined,
+        ...(locationData ? toLocationContext(locationData) : undefined),
+        CommandAuthorized: commandAuthorized,
+        MessageThreadId: threadSpec.id,
+        IsForum: isForum,
+        OriginatingChannel: "telegram",
+        OriginatingTo: `telegram:${chatId}`,
+    });
+    const pinnedMainDmOwner = !isGroup
+        ? resolvePinnedMainDmOwnerFromAllowlist({
+            dmScope: cfg.session?.dmScope,
+            allowFrom: dmAllowFrom,
+            normalizeEntry: (entry) => normalizeAllowFrom([entry]).entries[0],
+        })
+        : null;
+    const updateLastRouteSessionKey = resolveInboundLastRouteSessionKey({
+        route,
+        sessionKey: route.sessionKey,
+    });
+    await recordInboundSession({
+        storePath,
+        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+        ctx: ctxPayload,
+        updateLastRoute: !isGroup
+            ? {
+                sessionKey: updateLastRouteSessionKey,
+                channel: "telegram",
+                to: `telegram:${chatId}`,
+                accountId: route.accountId,
+                threadId: dmThreadId != null ? String(dmThreadId) : undefined,
+                mainDmOwnerPin: updateLastRouteSessionKey === route.mainSessionKey && pinnedMainDmOwner && senderId
+                    ? {
+                        ownerRecipient: pinnedMainDmOwner,
+                        senderRecipient: senderId,
+                        onSkip: ({ ownerRecipient, senderRecipient }) => {
+                            logVerbose(`telegram: skip main-session last route for ${senderRecipient} (pinned owner ${ownerRecipient})`);
+                        },
+                    }
+                    : undefined,
+            }
+            : undefined,
+        onRecordError: (err) => {
+            logVerbose(`telegram: failed updating session meta: ${String(err)}`);
+        },
+    });
+    if (replyTarget && shouldLogVerbose()) {
+        const preview = replyTarget.body.replace(/\s+/g, " ").slice(0, 120);
+        logVerbose(`telegram reply-context: replyToId=${replyTarget.id} replyToSender=${replyTarget.sender} replyToBody="${preview}"`);
+    }
+    if (forwardOrigin && shouldLogVerbose()) {
+        logVerbose(`telegram forward-context: forwardedFrom="${forwardOrigin.from}" type=${forwardOrigin.fromType}`);
+    }
+    if (shouldLogVerbose()) {
+        const preview = body.slice(0, 200).replace(/\n/g, "\\n");
+        const mediaInfo = allMedia.length > 1 ? ` mediaCount=${allMedia.length}` : "";
+        const topicInfo = resolvedThreadId != null ? ` topic=${resolvedThreadId}` : "";
+        logVerbose(`telegram inbound: chatId=${chatId} from=${ctxPayload.From} len=${body.length}${mediaInfo}${topicInfo} preview="${preview}"`);
+    }
+    return {
+        ctxPayload,
+        skillFilter,
+    };
+}

package/dist/telegram/bot-message-context.types.js

@@ -0,0 +1 @@
+export {};

package/dist/telegram/bot-native-commands.test-helpers.js

@@ -0,0 +1,117 @@
+import { vi } from "vitest";
+import { registerTelegramNativeCommands } from "./bot-native-commands.js";
+const pluginCommandMocks = vi.hoisted(() => ({
+    getPluginCommandSpecs: vi.fn(() => []),
+    matchPluginCommand: vi.fn(() => null),
+    executePluginCommand: vi.fn(async () => ({ text: "ok" })),
+}));
+export const getPluginCommandSpecs = pluginCommandMocks.getPluginCommandSpecs;
+export const matchPluginCommand = pluginCommandMocks.matchPluginCommand;
+export const executePluginCommand = pluginCommandMocks.executePluginCommand;
+vi.mock("../../../src/plugins/commands.js", () => ({
+    getPluginCommandSpecs: pluginCommandMocks.getPluginCommandSpecs,
+    matchPluginCommand: pluginCommandMocks.matchPluginCommand,
+    executePluginCommand: pluginCommandMocks.executePluginCommand,
+}));
+const deliveryMocks = vi.hoisted(() => ({
+    deliverReplies: vi.fn(async () => { }),
+}));
+export const deliverReplies = deliveryMocks.deliverReplies;
+vi.mock("./bot/delivery.js", () => ({ deliverReplies: deliveryMocks.deliverReplies }));
+vi.mock("../../../src/pairing/pairing-store.js", () => ({
+    readChannelAllowFromStore: vi.fn(async () => []),
+}));
+export function createNativeCommandTestParams(params = {}) {
+    const log = vi.fn();
+    return {
+        bot: params.bot ??
+            {
+                api: {
+                    setMyCommands: vi.fn().mockResolvedValue(undefined),
+                    sendMessage: vi.fn().mockResolvedValue(undefined),
+                },
+                command: vi.fn(),
+            },
+        cfg: params.cfg ?? {},
+        runtime: params.runtime ?? { log },
+        accountId: params.accountId ?? "default",
+        telegramCfg: params.telegramCfg ?? {},
+        allowFrom: params.allowFrom ?? [],
+        groupAllowFrom: params.groupAllowFrom ?? [],
+        replyToMode: params.replyToMode ?? "off",
+        textLimit: params.textLimit ?? 4000,
+        useAccessGroups: params.useAccessGroups ?? false,
+        nativeEnabled: params.nativeEnabled ?? true,
+        nativeSkillsEnabled: params.nativeSkillsEnabled ?? false,
+        nativeDisabledExplicit: params.nativeDisabledExplicit ?? false,
+        resolveGroupPolicy: params.resolveGroupPolicy ??
+            (() => ({
+                allowlistEnabled: false,
+                allowed: true,
+            })),
+        resolveTelegramGroupConfig: params.resolveTelegramGroupConfig ??
+            (() => ({ groupConfig: undefined, topicConfig: undefined })),
+        shouldSkipUpdate: params.shouldSkipUpdate ?? (() => false),
+        opts: params.opts ?? { token: "token" },
+    };
+}
+export function createNativeCommandsHarness(params) {
+    const handlers = {};
+    const sendMessage = vi.fn(async () => undefined);
+    const setMyCommands = vi.fn(async () => undefined);
+    const log = vi.fn();
+    const bot = {
+        api: {
+            setMyCommands,
+            sendMessage,
+        },
+        command: (name, handler) => {
+            handlers[name] = handler;
+        },
+    };
+    registerTelegramNativeCommands({
+        bot: bot,
+        cfg: params?.cfg ?? {},
+        runtime: params?.runtime ?? { log },
+        accountId: "default",
+        telegramCfg: params?.telegramCfg ?? {},
+        allowFrom: params?.allowFrom ?? [],
+        groupAllowFrom: params?.groupAllowFrom ?? [],
+        replyToMode: "off",
+        textLimit: 4000,
+        useAccessGroups: params?.useAccessGroups ?? false,
+        nativeEnabled: params?.nativeEnabled ?? true,
+        nativeSkillsEnabled: false,
+        nativeDisabledExplicit: false,
+        resolveGroupPolicy: params?.resolveGroupPolicy ??
+            (() => ({
+                allowlistEnabled: false,
+                allowed: true,
+            })),
+        resolveTelegramGroupConfig: () => ({
+            groupConfig: params?.groupConfig,
+            topicConfig: undefined,
+        }),
+        shouldSkipUpdate: () => false,
+        opts: { token: "token" },
+    });
+    return { handlers, sendMessage, setMyCommands, log, bot };
+}
+export function createTelegramGroupCommandContext(params) {
+    return {
+        message: {
+            chat: { id: -100999, type: "supergroup", is_forum: true },
+            from: {
+                id: params?.senderId ?? 12345,
+                username: params?.username ?? "testuser",
+            },
+            message_thread_id: params?.threadId ?? 42,
+            message_id: 1,
+            date: 1700000000,
+        },
+        match: "",
+    };
+}
+export function findNotAuthorizedCalls(sendMessage) {
+    return sendMessage.mock.calls.filter((call) => typeof call[1] === "string" && call[1].includes("not authorized"));
+}

package/dist/telegram/bot.media.e2e-harness.js

@@ -0,0 +1,81 @@
+import { beforeEach, vi } from "vitest";
+import { resetInboundDedupe } from "../auto-reply/reply/inbound-dedupe.js";
+export const useSpy = vi.fn();
+export const middlewareUseSpy = vi.fn();
+export const onSpy = vi.fn();
+export const stopSpy = vi.fn();
+export const sendChatActionSpy = vi.fn();
+const apiStub = {
+    config: { use: useSpy },
+    sendChatAction: sendChatActionSpy,
+    setMyCommands: vi.fn(async () => undefined),
+};
+beforeEach(() => {
+    resetInboundDedupe();
+});
+vi.mock("grammy", () => ({
+    Bot: class {
+        token;
+        api = apiStub;
+        use = middlewareUseSpy;
+        on = onSpy;
+        command = vi.fn();
+        stop = stopSpy;
+        catch = vi.fn();
+        constructor(token) {
+            this.token = token;
+        }
+    },
+    InputFile: class {
+    },
+    webhookCallback: vi.fn(),
+}));
+vi.mock("@grammyjs/runner", () => ({
+    sequentialize: () => vi.fn(),
+}));
+const throttlerSpy = vi.fn(() => "throttler");
+vi.mock("@grammyjs/transformer-throttler", () => ({
+    apiThrottler: () => throttlerSpy(),
+}));
+vi.mock("../media/store.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        saveMediaBuffer: vi.fn(async (buffer, contentType) => ({
+            id: "media",
+            path: "/tmp/telegram-media",
+            size: buffer.byteLength,
+            contentType: contentType ?? "application/octet-stream",
+        })),
+    };
+});
+vi.mock("../config/config.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        loadConfig: () => ({
+            channels: { telegram: { dmPolicy: "open", allowFrom: ["*"] } },
+        }),
+    };
+});
+vi.mock("../config/sessions.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        updateLastRoute: vi.fn(async () => undefined),
+    };
+});
+vi.mock("../pairing/pairing-store.js", () => ({
+    readChannelAllowFromStore: vi.fn(async () => []),
+    upsertChannelPairingRequest: vi.fn(async () => ({
+        code: "PAIRCODE",
+        created: true,
+    })),
+}));
+vi.mock("../auto-reply/reply.js", () => {
+    const replySpy = vi.fn(async (_ctx, opts) => {
+        await opts?.onReplyStart?.();
+        return undefined;
+    });
+    return { getReplyFromConfig: replySpy, __replySpy: replySpy };
+});

package/dist/telegram/bot.media.test-utils.js

@@ -0,0 +1,81 @@
+import { afterEach, beforeAll, beforeEach, expect, vi } from "vitest";
+import * as ssrf from "../../../src/infra/net/ssrf.js";
+import { onSpy, sendChatActionSpy } from "./bot.media.e2e-harness.js";
+export const cacheStickerSpy = vi.fn();
+export const getCachedStickerSpy = vi.fn();
+export const describeStickerImageSpy = vi.fn();
+const resolvePinnedHostname = ssrf.resolvePinnedHostname;
+const lookupMock = vi.fn();
+let resolvePinnedHostnameSpy = null;
+export const TELEGRAM_TEST_TIMINGS = {
+    mediaGroupFlushMs: 20,
+    textFragmentGapMs: 30,
+};
+const TELEGRAM_BOT_IMPORT_TIMEOUT_MS = process.platform === "win32" ? 180_000 : 150_000;
+let createTelegramBotRef;
+let replySpyRef;
+export async function createBotHandler() {
+    return createBotHandlerWithOptions({});
+}
+export async function createBotHandlerWithOptions(options) {
+    onSpy.mockClear();
+    replySpyRef.mockClear();
+    sendChatActionSpy.mockClear();
+    const runtimeError = options.runtimeError ?? vi.fn();
+    const runtimeLog = options.runtimeLog ?? vi.fn();
+    createTelegramBotRef({
+        token: "tok",
+        testTimings: TELEGRAM_TEST_TIMINGS,
+        ...(options.proxyFetch ? { proxyFetch: options.proxyFetch } : {}),
+        runtime: {
+            log: runtimeLog,
+            error: runtimeError,
+            exit: () => {
+                throw new Error("exit");
+            },
+        },
+    });
+    const handler = onSpy.mock.calls.find((call) => call[0] === "message")?.[1];
+    expect(handler).toBeDefined();
+    return { handler, replySpy: replySpyRef, runtimeError };
+}
+export function mockTelegramFileDownload(params) {
+    return vi.spyOn(globalThis, "fetch").mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        headers: { get: () => params.contentType },
+        arrayBuffer: async () => params.bytes.buffer,
+    });
+}
+export function mockTelegramPngDownload() {
+    return vi.spyOn(globalThis, "fetch").mockResolvedValue({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        headers: { get: () => "image/png" },
+        arrayBuffer: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]).buffer,
+    });
+}
+beforeEach(() => {
+    vi.useRealTimers();
+    lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }]);
+    resolvePinnedHostnameSpy = vi
+        .spyOn(ssrf, "resolvePinnedHostname")
+        .mockImplementation((hostname) => resolvePinnedHostname(hostname, lookupMock));
+});
+afterEach(() => {
+    lookupMock.mockClear();
+    resolvePinnedHostnameSpy?.mockRestore();
+    resolvePinnedHostnameSpy = null;
+});
+beforeAll(async () => {
+    ({ createTelegramBot: createTelegramBotRef } = await import("./bot.js"));
+    const replyModule = await import("../../../src/auto-reply/reply.js");
+    replySpyRef = replyModule.__replySpy;
+}, TELEGRAM_BOT_IMPORT_TIMEOUT_MS);
+vi.mock("./sticker-cache.js", () => ({
+    cacheSticker: (...args) => cacheStickerSpy(...args),
+    getCachedSticker: (...args) => getCachedStickerSpy(...args),
+    describeStickerImage: (...args) => describeStickerImageSpy(...args),
+}));