@foxden-app/foxclaw 0.2.0

package/dist/telegram/api.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import https from 'node:https';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+const API_HOST = 'api.telegram.org';
+export async function callTelegramApi(botToken, method, body) {
+    const payload = JSON.stringify(body);
+    return new Promise((resolve, reject) => {
+        const request = https.request({
+            host: API_HOST,
+            port: 443,
+            path: `/bot${botToken}/${method}`,
+            method: 'POST',
+            family: 4,
+            headers: {
+                'content-type': 'application/json',
+                'content-length': Buffer.byteLength(payload),
+            },
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            response.on('end', () => {
+                try {
+                    const text = Buffer.concat(chunks).toString('utf8');
+                    resolve(JSON.parse(text));
+                }
+                catch (error) {
+                    reject(new Error(`Failed to parse Telegram response: ${String(error)}`));
+                }
+            });
+        });
+        request.on('error', reject);
+        request.setTimeout(20_000, () => {
+            request.destroy(new Error(`Telegram API request timed out for ${method}`));
+        });
+        request.write(payload);
+        request.end();
+    });
+}
+export async function getTelegramFile(botToken, fileId) {
+    const result = await callTelegramApi(botToken, 'getFile', { file_id: fileId });
+    if (!result.ok || !result.result) {
+        throw new Error(result.description || `Failed to resolve Telegram file ${fileId}`);
+    }
+    return result.result;
+}
+export async function downloadTelegramFile(botToken, remoteFilePath, destinationPath) {
+    await fs.promises.mkdir(path.dirname(destinationPath), { recursive: true });
+    const tempPath = `${destinationPath}.tmp-${process.pid}-${Date.now()}`;
+    let response = null;
+    try {
+        response = await new Promise((resolve, reject) => {
+            const request = https.get({
+                host: API_HOST,
+                port: 443,
+                path: `/file/bot${botToken}/${remoteFilePath}`,
+                family: 4,
+            }, (incoming) => {
+                const statusCode = incoming.statusCode ?? 500;
+                if (statusCode >= 400) {
+                    incoming.resume();
+                    reject(new Error(`Telegram file download failed with status ${statusCode}`));
+                    return;
+                }
+                resolve(incoming);
+            });
+            request.on('error', reject);
+            request.setTimeout(20_000, () => {
+                request.destroy(new Error(`Telegram file download timed out for ${remoteFilePath}`));
+            });
+        });
+        let bytesWritten = 0;
+        response.on('data', (chunk) => {
+            bytesWritten += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
+        });
+        await pipeline(response, fs.createWriteStream(tempPath));
+        await fs.promises.rename(tempPath, destinationPath);
+        return bytesWritten;
+    }
+    catch (error) {
+        await fs.promises.rm(tempPath, { force: true }).catch(() => { });
+        throw error;
+    }
+    finally {
+        response?.destroy();
+    }
+}

package/dist/telegram/gateway.d.ts

@@ -0,0 +1,76 @@
+import { EventEmitter } from 'node:events';
+import { type TelegramRemoteFile } from './api.js';
+import type { BridgeStore } from '../store/database.js';
+import type { Logger } from '../logger.js';
+import type { TelegramMessageEntity } from './addressing.js';
+import type { TelegramInboundAttachment } from './media.js';
+export interface TelegramTextEvent {
+    chatId: string;
+    topicId: number | null;
+    scopeId: string;
+    chatType: string;
+    userId: string;
+    text: string;
+    messageId: number;
+    attachments: TelegramInboundAttachment[];
+    entities: TelegramMessageEntity[];
+    replyToBot: boolean;
+    languageCode?: string;
+}
+export interface TelegramCallbackEvent {
+    chatId: string;
+    topicId: number | null;
+    scopeId: string;
+    userId: string;
+    data: string;
+    callbackQueryId: string;
+    messageId: number;
+    languageCode?: string;
+}
+export declare class TelegramGateway extends EventEmitter {
+    private readonly botToken;
+    private readonly allowedUserId;
+    private readonly allowedChatId;
+    private readonly pollIntervalMs;
+    private readonly store;
+    private readonly logger;
+    private running;
+    private botKey;
+    private botUsername;
+    private botUserId;
+    constructor(botToken: string, allowedUserId: string, allowedChatId: string | null, pollIntervalMs: number, store: BridgeStore, logger: Logger);
+    get username(): string | null;
+    start(): Promise<void>;
+    stop(): void;
+    sendMessage(chatId: string, text: string, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>, messageThreadId?: number | null): Promise<number>;
+    sendHtmlMessage(chatId: string, text: string, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>, messageThreadId?: number | null): Promise<number>;
+    sendMessageDraft(chatId: string, draftId: number, text: string, messageThreadId?: number | null): Promise<void>;
+    editMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>): Promise<void>;
+    editHtmlMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>): Promise<void>;
+    clearMessageInlineKeyboard(chatId: string, messageId: number): Promise<void>;
+    private sendMessageWithOptions;
+    private editMessageWithOptions;
+    deleteMessage(chatId: string, messageId: number): Promise<void>;
+    answerCallback(callbackQueryId: string, text?: string): Promise<void>;
+    sendTyping(chatId: string): Promise<void>;
+    sendTypingInThread(chatId: string, messageThreadId?: number | null): Promise<void>;
+    getFile(fileId: string): Promise<TelegramRemoteFile>;
+    downloadResolvedFile(remoteFilePath: string, destinationPath: string): Promise<number>;
+    private resolveBotIdentity;
+    private registerCommands;
+    private pollLoop;
+    private handleUpdate;
+    private isAllowedChat;
+}

package/dist/telegram/gateway.js

@@ -0,0 +1,383 @@
+import { EventEmitter } from 'node:events';
+import crypto from 'node:crypto';
+import { callTelegramApi, downloadTelegramFile, getTelegramFile } from './api.js';
+import { getTelegramCommands } from '../i18n.js';
+import { toTelegramBridgeScopeId } from '../core/bridge_scope.js';
+import { createTelegramScopeId } from './scope.js';
+export class TelegramGateway extends EventEmitter {
+    botToken;
+    allowedUserId;
+    allowedChatId;
+    pollIntervalMs;
+    store;
+    logger;
+    running = false;
+    botKey;
+    botUsername = null;
+    botUserId = null;
+    constructor(botToken, allowedUserId, allowedChatId, pollIntervalMs, store, logger) {
+        super();
+        this.botToken = botToken;
+        this.allowedUserId = allowedUserId;
+        this.allowedChatId = allowedChatId;
+        this.pollIntervalMs = pollIntervalMs;
+        this.store = store;
+        this.logger = logger;
+        this.botKey = `telegram:${crypto.createHash('sha256').update(this.botToken).digest('hex').slice(0, 8)}`;
+    }
+    get username() {
+        return this.botUsername;
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        await this.resolveBotIdentity();
+        await this.registerCommands();
+        void this.pollLoop();
+    }
+    stop() {
+        this.running = false;
+    }
+    async sendMessage(chatId, text, inlineKeyboard, messageThreadId) {
+        return this.sendMessageWithOptions(chatId, text, inlineKeyboard, undefined, messageThreadId);
+    }
+    async sendHtmlMessage(chatId, text, inlineKeyboard, messageThreadId) {
+        return this.sendMessageWithOptions(chatId, text, inlineKeyboard, 'HTML', messageThreadId);
+    }
+    async sendMessageDraft(chatId, draftId, text, messageThreadId) {
+        const result = await callTelegramApi(this.botToken, 'sendMessageDraft', {
+            chat_id: chatId,
+            draft_id: draftId,
+            text,
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
+            disable_web_page_preview: true,
+        });
+        if (!result.ok) {
+            throw new Error(result.description || 'Failed to send Telegram draft message');
+        }
+    }
+    async editMessage(chatId, messageId, text, inlineKeyboard) {
+        return this.editMessageWithOptions(chatId, messageId, text, inlineKeyboard);
+    }
+    async editHtmlMessage(chatId, messageId, text, inlineKeyboard) {
+        return this.editMessageWithOptions(chatId, messageId, text, inlineKeyboard, 'HTML');
+    }
+    async clearMessageInlineKeyboard(chatId, messageId) {
+        const result = await callTelegramApi(this.botToken, 'editMessageReplyMarkup', {
+            chat_id: chatId,
+            message_id: messageId,
+            reply_markup: { inline_keyboard: [] },
+        });
+        if (!result.ok && !String(result.description || '').includes('message is not modified')) {
+            throw new Error(result.description || 'Failed to clear Telegram message reply markup');
+        }
+    }
+    async sendMessageWithOptions(chatId, text, inlineKeyboard, parseMode, messageThreadId) {
+        const result = await callTelegramApi(this.botToken, 'sendMessage', {
+            chat_id: chatId,
+            text,
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
+            ...(inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+            ...(parseMode ? { parse_mode: parseMode } : {}),
+            disable_web_page_preview: true,
+        });
+        if (!result.ok || !result.result) {
+            throw new Error(result.description || 'Failed to send Telegram message');
+        }
+        return result.result.message_id;
+    }
+    async editMessageWithOptions(chatId, messageId, text, inlineKeyboard, parseMode) {
+        const result = await callTelegramApi(this.botToken, 'editMessageText', {
+            chat_id: chatId,
+            message_id: messageId,
+            text,
+            ...(inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+            ...(parseMode ? { parse_mode: parseMode } : {}),
+            disable_web_page_preview: true,
+        });
+        if (!result.ok && !String(result.description || '').includes('message is not modified')) {
+            throw new Error(result.description || 'Failed to edit Telegram message');
+        }
+    }
+    async deleteMessage(chatId, messageId) {
+        const result = await callTelegramApi(this.botToken, 'deleteMessage', {
+            chat_id: chatId,
+            message_id: messageId,
+        });
+        if (!result.ok) {
+            throw new Error(result.description || 'Failed to delete Telegram message');
+        }
+    }
+    async answerCallback(callbackQueryId, text = 'OK') {
+        await callTelegramApi(this.botToken, 'answerCallbackQuery', {
+            callback_query_id: callbackQueryId,
+            text,
+        });
+    }
+    async sendTyping(chatId) {
+        await callTelegramApi(this.botToken, 'sendChatAction', {
+            chat_id: chatId,
+            action: 'typing',
+        });
+    }
+    async sendTypingInThread(chatId, messageThreadId) {
+        await callTelegramApi(this.botToken, 'sendChatAction', {
+            chat_id: chatId,
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
+            action: 'typing',
+        });
+    }
+    async getFile(fileId) {
+        return getTelegramFile(this.botToken, fileId);
+    }
+    async downloadResolvedFile(remoteFilePath, destinationPath) {
+        return downloadTelegramFile(this.botToken, remoteFilePath, destinationPath);
+    }
+    async resolveBotIdentity() {
+        const result = await callTelegramApi(this.botToken, 'getMe', {});
+        if (result.ok && result.result) {
+            this.botKey = `telegram:bot${result.result.id}`;
+            this.botUserId = result.result.id;
+            this.botUsername = result.result.username ?? null;
+        }
+    }
+    async registerCommands() {
+        await callTelegramApi(this.botToken, 'setMyCommands', {
+            commands: getTelegramCommands('zh'),
+        });
+        await callTelegramApi(this.botToken, 'setMyCommands', {
+            commands: getTelegramCommands('en'),
+            language_code: 'en',
+        });
+        await callTelegramApi(this.botToken, 'setMyCommands', {
+            commands: getTelegramCommands('zh'),
+            language_code: 'zh',
+        });
+    }
+    async pollLoop() {
+        while (this.running) {
+            try {
+                const offset = this.store.getTelegramOffset(this.botKey) + 1;
+                const result = await callTelegramApi(this.botToken, 'getUpdates', {
+                    timeout: Math.max(1, Math.floor(this.pollIntervalMs / 1000)),
+                    offset,
+                    allowed_updates: ['message', 'callback_query']
+                });
+                if (!result.ok || !result.result) {
+                    this.logger.warn('telegram.getUpdates failed', result.description);
+                    await sleep(this.pollIntervalMs);
+                    continue;
+                }
+                for (const update of result.result) {
+                    this.store.setTelegramOffset(this.botKey, update.update_id);
+                    await this.handleUpdate(update);
+                }
+            }
+            catch (error) {
+                this.logger.error('telegram.pollLoop error', toErrorMeta(error));
+                await sleep(this.pollIntervalMs);
+            }
+        }
+    }
+    async handleUpdate(update) {
+        if (update.message && update.message.from && this.isAllowedChat(update.message.chat)) {
+            if (String(update.message.from.id) !== this.allowedUserId)
+                return;
+            const attachments = extractAttachments(update.message);
+            const text = update.message.text ?? update.message.caption ?? '';
+            const topicId = update.message.message_thread_id ?? null;
+            const scopeId = toTelegramBridgeScopeId(createTelegramScopeId(String(update.message.chat.id), topicId));
+            const entities = update.message.text ? (update.message.entities ?? []) : (update.message.caption_entities ?? []);
+            const replyToBot = this.botUserId !== null && update.message.reply_to_message?.from?.id === this.botUserId;
+            if (text || attachments.length > 0) {
+                this.emit('text', {
+                    chatId: String(update.message.chat.id),
+                    topicId,
+                    scopeId,
+                    chatType: update.message.chat.type,
+                    userId: String(update.message.from.id),
+                    text,
+                    messageId: update.message.message_id,
+                    attachments,
+                    entities,
+                    replyToBot,
+                    ...(update.message.from.language_code ? { languageCode: update.message.from.language_code } : {}),
+                });
+                return;
+            }
+        }
+        if (update.callback_query?.data && update.callback_query.from && update.callback_query.message) {
+            if (String(update.callback_query.from.id) !== this.allowedUserId)
+                return;
+            if (!this.isAllowedChat(update.callback_query.message.chat))
+                return;
+            const topicId = update.callback_query.message.message_thread_id ?? null;
+            this.emit('callback', {
+                chatId: String(update.callback_query.message.chat.id),
+                topicId,
+                scopeId: toTelegramBridgeScopeId(createTelegramScopeId(String(update.callback_query.message.chat.id), topicId)),
+                userId: String(update.callback_query.from.id),
+                data: update.callback_query.data,
+                callbackQueryId: update.callback_query.id,
+                messageId: update.callback_query.message.message_id,
+                ...(update.callback_query.from.language_code ? { languageCode: update.callback_query.from.language_code } : {}),
+            });
+        }
+    }
+    isAllowedChat(chat) {
+        if (chat.type === 'private') {
+            return true;
+        }
+        if (this.allowedChatId) {
+            return String(chat.id) === this.allowedChatId;
+        }
+        return false;
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function extractAttachments(message) {
+    const attachments = [];
+    const largestPhoto = pickLargestPhoto(message.photo ?? []);
+    if (largestPhoto) {
+        attachments.push({
+            kind: 'photo',
+            fileId: largestPhoto.file_id,
+            fileUniqueId: largestPhoto.file_unique_id,
+            fileName: null,
+            mimeType: 'image/jpeg',
+            fileSize: largestPhoto.file_size ?? null,
+            width: largestPhoto.width,
+            height: largestPhoto.height,
+            durationSeconds: null,
+            isAnimated: false,
+            isVideo: false,
+        });
+    }
+    if (message.document) {
+        attachments.push({
+            kind: 'document',
+            fileId: message.document.file_id,
+            fileUniqueId: message.document.file_unique_id,
+            fileName: message.document.file_name ?? null,
+            mimeType: message.document.mime_type ?? null,
+            fileSize: message.document.file_size ?? null,
+            width: null,
+            height: null,
+            durationSeconds: null,
+            isAnimated: false,
+            isVideo: false,
+        });
+    }
+    if (message.audio) {
+        attachments.push({
+            kind: 'audio',
+            fileId: message.audio.file_id,
+            fileUniqueId: message.audio.file_unique_id,
+            fileName: message.audio.file_name ?? null,
+            mimeType: message.audio.mime_type ?? null,
+            fileSize: message.audio.file_size ?? null,
+            width: null,
+            height: null,
+            durationSeconds: message.audio.duration ?? null,
+            isAnimated: false,
+            isVideo: false,
+        });
+    }
+    if (message.voice) {
+        attachments.push({
+            kind: 'voice',
+            fileId: message.voice.file_id,
+            fileUniqueId: message.voice.file_unique_id,
+            fileName: null,
+            mimeType: message.voice.mime_type ?? null,
+            fileSize: message.voice.file_size ?? null,
+            width: null,
+            height: null,
+            durationSeconds: message.voice.duration ?? null,
+            isAnimated: false,
+            isVideo: false,
+        });
+    }
+    if (message.video) {
+        attachments.push({
+            kind: 'video',
+            fileId: message.video.file_id,
+            fileUniqueId: message.video.file_unique_id,
+            fileName: message.video.file_name ?? null,
+            mimeType: message.video.mime_type ?? null,
+            fileSize: message.video.file_size ?? null,
+            width: message.video.width ?? null,
+            height: message.video.height ?? null,
+            durationSeconds: message.video.duration ?? null,
+            isAnimated: false,
+            isVideo: true,
+        });
+    }
+    if (message.animation) {
+        attachments.push({
+            kind: 'animation',
+            fileId: message.animation.file_id,
+            fileUniqueId: message.animation.file_unique_id,
+            fileName: message.animation.file_name ?? null,
+            mimeType: message.animation.mime_type ?? null,
+            fileSize: message.animation.file_size ?? null,
+            width: message.animation.width ?? null,
+            height: message.animation.height ?? null,
+            durationSeconds: message.animation.duration ?? null,
+            isAnimated: true,
+            isVideo: message.animation.mime_type?.startsWith('video/') ?? false,
+        });
+    }
+    if (message.sticker) {
+        attachments.push({
+            kind: 'sticker',
+            fileId: message.sticker.file_id,
+            fileUniqueId: message.sticker.file_unique_id,
+            fileName: null,
+            mimeType: null,
+            fileSize: message.sticker.file_size ?? null,
+            width: message.sticker.width,
+            height: message.sticker.height,
+            durationSeconds: null,
+            isAnimated: message.sticker.is_animated ?? false,
+            isVideo: message.sticker.is_video ?? false,
+        });
+    }
+    if (message.video_note) {
+        attachments.push({
+            kind: 'videoNote',
+            fileId: message.video_note.file_id,
+            fileUniqueId: message.video_note.file_unique_id,
+            fileName: null,
+            mimeType: 'video/mp4',
+            fileSize: message.video_note.file_size ?? null,
+            width: message.video_note.length ?? null,
+            height: message.video_note.length ?? null,
+            durationSeconds: message.video_note.duration ?? null,
+            isAnimated: false,
+            isVideo: true,
+        });
+    }
+    return attachments;
+}
+function pickLargestPhoto(photos) {
+    if (photos.length === 0)
+        return null;
+    return photos.reduce((current, candidate) => {
+        const currentArea = current.width * current.height;
+        const candidateArea = candidate.width * candidate.height;
+        if (candidateArea !== currentArea) {
+            return candidateArea > currentArea ? candidate : current;
+        }
+        return (candidate.file_size ?? 0) > (current.file_size ?? 0) ? candidate : current;
+    });
+}
+function toErrorMeta(error) {
+    if (error instanceof Error) {
+        return { message: error.message, stack: error.stack };
+    }
+    return { error: String(error) };
+}

package/dist/telegram/media.d.ts

@@ -0,0 +1,34 @@
+export declare const TELEGRAM_INBOX_DIR = ".telegram-inbox";
+export declare const TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES: number;
+export type TelegramAttachmentKind = 'photo' | 'document' | 'audio' | 'voice' | 'video' | 'animation' | 'sticker' | 'videoNote';
+export interface TelegramInboundAttachment {
+    kind: TelegramAttachmentKind;
+    fileId: string;
+    fileUniqueId: string;
+    fileName: string | null;
+    mimeType: string | null;
+    fileSize: number | null;
+    width: number | null;
+    height: number | null;
+    durationSeconds: number | null;
+    isAnimated: boolean;
+    isVideo: boolean;
+    /** When set, {@link stageAttachments} copies this file instead of Telegram Bot API download. */
+    localPath?: string;
+}
+export interface StagedTelegramAttachment extends TelegramInboundAttachment {
+    fileName: string;
+    localPath: string;
+    relativePath: string;
+    nativeImage: boolean;
+}
+interface PlannedAttachmentPath {
+    fileName: string;
+    localPath: string;
+    relativePath: string;
+}
+export declare function isNativeImageAttachment(attachment: TelegramInboundAttachment): boolean;
+export declare function planAttachmentStoragePath(cwd: string, threadId: string, attachment: TelegramInboundAttachment, remoteFilePath?: string | null, now?: Date): PlannedAttachmentPath;
+export declare function buildAttachmentPrompt(userText: string, attachments: readonly StagedTelegramAttachment[]): string;
+export declare function summarizeTelegramInput(text: string, attachments: readonly TelegramInboundAttachment[]): string;
+export {};