@holon-run/agentinbox 1.0.4 → 1.0.5

package/dist/src/sources/feishu.js

@@ -3,12 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FeishuDeliveryAdapter = exports.FeishuUxcClient = exports.DEFAULT_FEISHU_EVENT_TYPES = exports.FEISHU_IM_SCHEMA_URL = exports.FEISHU_OPENAPI_ENDPOINT = void 0;
 exports.feishuDeliveryOperationsForHandle = feishuDeliveryOperationsForHandle;
 exports.invokeFeishuDeliveryOperation = invokeFeishuDeliveryOperation;
+exports.feishuFollowTemplateSpec = feishuFollowTemplateSpec;
+exports.expandFeishuFollowTemplate = expandFeishuFollowTemplate;
+exports.feishuSourceOperations = feishuSourceOperations;
+exports.invokeFeishuSourceOperation = invokeFeishuSourceOperation;
 exports.normalizeFeishuBotEvent = normalizeFeishuBotEvent;
 exports.parseFeishuSourceConfig = parseFeishuSourceConfig;
 const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
 exports.FEISHU_OPENAPI_ENDPOINT = "https://open.feishu.cn/open-apis";
 exports.FEISHU_IM_SCHEMA_URL = "https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json";
+const FEISHU_BOT_SCHEMA_FILE = (0, node_path_1.join)((0, node_os_1.tmpdir)(), "agentinbox-feishu-bot.openapi.json");
 exports.DEFAULT_FEISHU_EVENT_TYPES = ["im.message.receive_v1"];
+const DEFAULT_CONTEXT_BOUND_SECONDS = 7 * 24 * 60 * 60;
 class FeishuUxcClient {
     client;
     constructor(client = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env })) {
@@ -18,13 +27,13 @@ class FeishuUxcClient {
         await this.client.call({
             endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
             operation: "post:/im/v1/messages",
-            payload: {
+            payload: compactPayload({
                 receive_id_type: "chat_id",
                 receive_id: input.chatId,
                 msg_type: input.msgType,
                 content: input.content,
-                uuid: input.uuid ?? null,
-            },
+                uuid: input.uuid,
+            }),
             options: {
                 auth: input.auth,
                 schema_url: input.schemaUrl ?? exports.FEISHU_IM_SCHEMA_URL,
@@ -35,18 +44,127 @@ class FeishuUxcClient {
         await this.client.call({
             endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
             operation: "post:/im/v1/messages/{message_id}/reply",
-            payload: {
+            payload: compactPayload({
                 message_id: input.messageId,
                 msg_type: input.msgType,
                 content: input.content,
-                reply_in_thread: input.replyInThread ?? null,
-                uuid: input.uuid ?? null,
+                reply_in_thread: input.replyInThread,
+                uuid: input.uuid,
+            }),
+            options: {
+                auth: input.auth,
+                schema_url: input.schemaUrl ?? exports.FEISHU_IM_SCHEMA_URL,
+            },
+        });
+    }
+    async uploadFile(input) {
+        const response = await this.client.call({
+            endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
+            operation: "post:/im/v1/files",
+            payload: {
+                file_type: input.fileType ?? "stream",
+                file_name: input.fileName,
+                file: input.filePath,
+            },
+            options: {
+                auth: input.auth,
+                schema_url: input.schemaUrl ?? exports.FEISHU_IM_SCHEMA_URL,
+            },
+        });
+        const fileKey = findStringField(response.data, "file_key");
+        if (!fileKey) {
+            throw new Error("Feishu file upload response did not include file_key");
+        }
+        return fileKey;
+    }
+    async getMessage(input) {
+        const response = await this.client.call({
+            endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
+            operation: "get:/im/v1/messages/{message_id}",
+            payload: {
+                message_id: input.messageId,
+            },
+            options: {
+                auth: input.auth,
+                schema_url: input.schemaUrl ?? exports.FEISHU_IM_SCHEMA_URL,
+            },
+        });
+        return response.data;
+    }
+    async listMessages(input) {
+        const payload = {
+            container_id_type: "chat",
+            container_id: input.chatId,
+            page_size: input.pageSize ?? 20,
+            sort_type: input.sort ?? "ByCreateTimeAsc",
+            card_msg_content_type: "raw_card_content",
+        };
+        if (input.startTime) {
+            payload.start_time = input.startTime;
+        }
+        if (input.endTime) {
+            payload.end_time = input.endTime;
+        }
+        if (input.pageToken) {
+            payload.page_token = input.pageToken;
+        }
+        const response = await this.client.call({
+            endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
+            operation: "get:/im/v1/messages",
+            payload,
+            options: {
+                auth: input.auth,
+                schema_url: input.schemaUrl ?? exports.FEISHU_IM_SCHEMA_URL,
+            },
+        });
+        return response.data;
+    }
+    async getBotOpenId(input) {
+        const response = await this.client.call({
+            endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
+            operation: "get:/bot/v3/info",
+            payload: {},
+            options: {
+                auth: input.auth,
+                schema_url: ensureFeishuBotSchemaFile(),
+                refresh_schema: true,
+                no_cache: true,
+            },
+        });
+        const openId = findStringField(response.data, "open_id");
+        if (!openId) {
+            throw new Error("Feishu bot info response did not include bot.open_id");
+        }
+        return openId;
+    }
+    async listChats(input) {
+        const response = await this.client.call({
+            endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
+            operation: "get:/im/v1/chats",
+            payload: compactPayload({
+                page_size: input.pageSize ?? 20,
+                page_token: input.pageToken,
+            }),
+            options: {
+                auth: input.auth,
+                schema_url: input.schemaUrl ?? exports.FEISHU_IM_SCHEMA_URL,
+            },
+        });
+        return response.data;
+    }
+    async getChat(input) {
+        const response = await this.client.call({
+            endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
+            operation: "get:/im/v1/chats/{chat_id}",
+            payload: {
+                chat_id: input.chatId,
             },
             options: {
                 auth: input.auth,
                 schema_url: input.schemaUrl ?? exports.FEISHU_IM_SCHEMA_URL,
             },
         });
+        return response.data;
     }
 }
 exports.FeishuUxcClient = FeishuUxcClient;
@@ -64,7 +182,9 @@ function feishuDeliveryOperationsForHandle(handle) {
     if (handle.surface !== "message_reply" && handle.surface !== "chat_message") {
         return [];
     }
-    return [{
+    const commonProperties = commonDeliveryInputSchemaProperties();
+    return [
+        {
             name: "send_text",
             title: handle.surface === "message_reply" ? "Reply With Text" : "Send Text Message",
             inputSchema: {
@@ -73,29 +193,129 @@ function feishuDeliveryOperationsForHandle(handle) {
                 required: ["text"],
                 properties: {
                     text: { type: "string", minLength: 1 },
-                    endpoint: { type: "string", minLength: 1 },
-                    schemaUrl: { type: "string", minLength: 1 },
-                    schema_url: { type: "string", minLength: 1 },
-                    uxcAuth: { type: "string", minLength: 1 },
-                    auth: { type: "string", minLength: 1 },
-                    replyInThread: { type: "boolean" },
-                    reply_in_thread: { type: "boolean" },
-                    uuid: { type: "string", minLength: 1 },
+                    ...commonProperties,
                 },
             },
             canonicalTextAlias: true,
-        }];
+        },
+        {
+            name: "send_post",
+            title: handle.surface === "message_reply" ? "Reply With Rich Text" : "Send Rich Text Message",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                anyOf: [
+                    { required: ["blocks"] },
+                    { required: ["paragraphs"] },
+                    { required: ["content"] },
+                ],
+                properties: {
+                    title: { type: "string" },
+                    locale: { type: "string", minLength: 1 },
+                    blocks: {
+                        type: "array",
+                        items: { type: "object", additionalProperties: true },
+                    },
+                    paragraphs: {
+                        type: "array",
+                        items: {
+                            type: "array",
+                            items: { type: "object", additionalProperties: true },
+                        },
+                    },
+                    content: {
+                        anyOf: [
+                            { type: "string", minLength: 1 },
+                            { type: "object", additionalProperties: true },
+                        ],
+                    },
+                    ...commonProperties,
+                },
+            },
+        },
+        {
+            name: "send_file",
+            title: handle.surface === "message_reply" ? "Reply With File" : "Send File Message",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                anyOf: [
+                    { required: ["fileKey"] },
+                    { required: ["file_key"] },
+                ],
+                properties: {
+                    fileKey: { type: "string", minLength: 1 },
+                    file_key: { type: "string", minLength: 1 },
+                    ...commonProperties,
+                },
+            },
+        },
+        {
+            name: "send_file_from_path",
+            title: handle.surface === "message_reply" ? "Upload And Reply With File" : "Upload And Send File",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                anyOf: [
+                    { required: ["filePath"] },
+                    { required: ["file_path"] },
+                ],
+                properties: {
+                    filePath: { type: "string", minLength: 1 },
+                    file_path: { type: "string", minLength: 1 },
+                    fileName: { type: "string", minLength: 1 },
+                    file_name: { type: "string", minLength: 1 },
+                    fileType: { type: "string", minLength: 1 },
+                    file_type: { type: "string", minLength: 1 },
+                    ...commonProperties,
+                },
+            },
+        },
+    ];
 }
 async function invokeFeishuDeliveryOperation(handle, operation, input, client = new FeishuUxcClient()) {
-    if (operation !== "send_text") {
-        throw new Error(`unknown Feishu delivery operation: ${operation}`);
+    const config = parseDeliveryConfig(input);
+    if (operation === "send_text") {
+        const text = asString(input.text);
+        if (!text || text.trim().length === 0) {
+            throw new Error("send_text requires input.text");
+        }
+        await sendFeishuMessage(handle, normalizeDeliveryMessage({ text }), config, client);
+        return { status: "sent", note: sentNote(handle, "text") };
     }
-    const text = asString(input.text);
-    if (!text || text.trim().length === 0) {
-        throw new Error("send_text requires input.text");
+    if (operation === "send_post") {
+        const message = normalizeFeishuPostMessage(input);
+        await sendFeishuMessage(handle, message, config, client);
+        return { status: "sent", note: sentNote(handle, "rich text") };
     }
-    const config = parseDeliveryConfig(input);
-    const message = normalizeDeliveryMessage({ text });
+    if (operation === "send_file") {
+        const fileKey = asString(input.fileKey) ?? asString(input.file_key);
+        if (!fileKey) {
+            throw new Error("send_file requires input.fileKey");
+        }
+        await sendFeishuMessage(handle, normalizeFeishuFileMessage(fileKey), config, client);
+        return { status: "sent", note: sentNote(handle, "file") };
+    }
+    if (operation === "send_file_from_path") {
+        const filePath = asString(input.filePath) ?? asString(input.file_path);
+        if (!filePath) {
+            throw new Error("send_file_from_path requires input.filePath");
+        }
+        const fileName = asString(input.fileName) ?? asString(input.file_name) ?? basename(filePath);
+        const fileKey = await client.uploadFile({
+            endpoint: config.endpoint,
+            schemaUrl: config.schemaUrl,
+            auth: config.auth,
+            filePath,
+            fileName,
+            fileType: asString(input.fileType) ?? asString(input.file_type) ?? "stream",
+        });
+        await sendFeishuMessage(handle, normalizeFeishuFileMessage(fileKey), config, client);
+        return { status: "sent", note: `${sentNote(handle, "file")} after upload` };
+    }
+    throw new Error(`unknown Feishu delivery operation: ${operation}`);
+}
+async function sendFeishuMessage(handle, message, config, client) {
     if (handle.surface === "message_reply") {
         await client.replyToMessage({
             endpoint: config.endpoint,
@@ -107,7 +327,7 @@ async function invokeFeishuDeliveryOperation(handle, operation, input, client =
             replyInThread: config.replyInThread,
             uuid: config.uuid,
         });
-        return { status: "sent", note: "sent Feishu message reply" };
+        return;
     }
     if (handle.surface === "chat_message") {
         await client.sendChatMessage({
@@ -119,25 +339,375 @@ async function invokeFeishuDeliveryOperation(handle, operation, input, client =
             content: message.content,
             uuid: config.uuid,
         });
-        return { status: "sent", note: "sent Feishu chat message" };
+        return;
     }
     throw new Error(`deliver send only supports canonical Feishu text surfaces; use deliver invoke for ${handle.surface}`);
 }
+function sentNote(handle, kind) {
+    return handle.surface === "message_reply"
+        ? `sent Feishu ${kind} message reply`
+        : `sent Feishu ${kind} chat message`;
+}
+function feishuFollowTemplateSpec() {
+    return [
+        {
+            templateId: "feishu.chat",
+            providerOrKind: "feishu",
+            label: "Feishu Chat",
+            description: "Follow messages from one Feishu/Lark chat.",
+            argsSchema: [
+                { name: "chatId", type: "string", required: true, description: "Feishu chat ID." },
+            ],
+        },
+        {
+            templateId: "feishu.mention",
+            providerOrKind: "feishu",
+            label: "Feishu Mention",
+            description: "Follow messages in one Feishu/Lark chat that mention a user or bot.",
+            argsSchema: [
+                { name: "chatId", type: "string", required: true, description: "Feishu chat ID." },
+                { name: "openId", type: "string", required: true, description: "Mentioned user or bot open_id." },
+            ],
+        },
+        {
+            templateId: "feishu.mentions",
+            providerOrKind: "feishu",
+            label: "Feishu Mentions",
+            description: "Follow messages across visible Feishu/Lark chats that mention a user or bot.",
+            argsSchema: [
+                { name: "openId", type: "string", required: false, description: "Mentioned user or bot open_id. Defaults to the configured app bot open_id." },
+            ],
+        },
+    ];
+}
+async function expandFeishuFollowTemplate(input, client = new FeishuUxcClient()) {
+    if (input.template !== "chat" && input.template !== "mention" && input.template !== "mentions") {
+        return null;
+    }
+    const args = input.args ?? {};
+    const chatId = asString(args.chatId);
+    if (input.template !== "mentions" && !chatId) {
+        throw new Error(`follow template feishu.${input.template} requires argument chatId`);
+    }
+    const config = parseFeishuSourceConfig(input.source);
+    const sourceKey = `feishu:${config.uxcAuth ?? input.source.configRef ?? "default"}:messages`;
+    const filter = chatId ? { metadata: { chatId } } : {};
+    let trackedResourceRef = chatId ? `chat:${chatId}` : "mentions";
+    if (input.template === "mention" || input.template === "mentions") {
+        const openId = asString(args.openId) ?? await resolveFeishuMentionOpenId(input, config, client);
+        if (!openId) {
+            throw new Error(`follow template feishu.${input.template} requires argument openId`);
+        }
+        filter.expr = `contains(metadata.mentionOpenIds, ${JSON.stringify(openId)})`;
+        trackedResourceRef = chatId ? `chat:${chatId}:mention:${openId}` : `mention:${openId}`;
+    }
+    return {
+        templateId: `feishu.${input.template}`,
+        sources: [
+            {
+                logicalName: "messages",
+                sourceType: "feishu_bot",
+                sourceKey,
+                configRef: input.source.configRef ?? null,
+                config: feishuFollowSourceConfig(input.source),
+            },
+        ],
+        subscriptions: [
+            {
+                sourceLogicalName: "messages",
+                filter,
+                trackedResourceRef,
+                cleanupPolicy: { mode: "manual" },
+            },
+        ],
+    };
+}
+async function resolveFeishuMentionOpenId(input, config, client) {
+    if (input.template !== "mentions") {
+        return null;
+    }
+    return client.getBotOpenId({
+        endpoint: config.endpoint,
+        auth: config.uxcAuth ?? input.source.configRef ?? undefined,
+    });
+}
+function feishuSourceOperations() {
+    return [
+        {
+            name: "get_message_context",
+            title: "Get Message Context",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["messageId"],
+                properties: {
+                    messageId: { type: "string", minLength: 1 },
+                    chatId: { type: "string", minLength: 1 },
+                    windowBefore: { type: "number", minimum: 0 },
+                    windowAfter: { type: "number", minimum: 0 },
+                },
+            },
+            outputSchema: {
+                type: "object",
+                additionalProperties: true,
+                required: ["anchorMessage", "chatWindowMessages", "threadMessages", "warnings", "deliveryHandle"],
+            },
+        },
+        {
+            name: "list_recent_messages",
+            title: "List Recent Messages",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["chatId"],
+                properties: {
+                    chatId: { type: "string", minLength: 1 },
+                    limit: { type: "number", minimum: 1, maximum: 50 },
+                    before: { type: "string", minLength: 1 },
+                    pageToken: { type: "string", minLength: 1 },
+                },
+            },
+            outputSchema: {
+                type: "object",
+                additionalProperties: true,
+                required: ["chatId", "messages", "warnings"],
+            },
+        },
+        {
+            name: "list_chats",
+            title: "List Chats",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    limit: { type: "number", minimum: 1, maximum: 50 },
+                    pageToken: { type: "string", minLength: 1 },
+                },
+            },
+            outputSchema: {
+                type: "object",
+                additionalProperties: true,
+                required: ["chats", "warnings"],
+            },
+        },
+        {
+            name: "search_chats",
+            title: "Search Chats",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["query"],
+                properties: {
+                    query: { type: "string", minLength: 1 },
+                    limit: { type: "number", minimum: 1, maximum: 50 },
+                    pageToken: { type: "string", minLength: 1 },
+                },
+            },
+            outputSchema: {
+                type: "object",
+                additionalProperties: true,
+                required: ["chats", "warnings"],
+            },
+        },
+        {
+            name: "get_chat",
+            title: "Get Chat",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["chatId"],
+                properties: {
+                    chatId: { type: "string", minLength: 1 },
+                },
+            },
+            outputSchema: {
+                type: "object",
+                additionalProperties: true,
+                required: ["chat", "warnings"],
+            },
+        },
+    ];
+}
+async function invokeFeishuSourceOperation(source, operation, input, client = new FeishuUxcClient()) {
+    if (operation === "list_recent_messages") {
+        return listRecentFeishuMessages(source, input, client);
+    }
+    if (operation === "list_chats") {
+        return listFeishuChats(source, input, client);
+    }
+    if (operation === "search_chats") {
+        return searchFeishuChats(source, input, client);
+    }
+    if (operation === "get_chat") {
+        return getFeishuChat(source, input, client);
+    }
+    if (operation !== "get_message_context") {
+        throw new Error(`unknown Feishu source operation: ${operation}`);
+    }
+    const messageId = asString(input.messageId);
+    if (!messageId) {
+        throw new Error("get_message_context requires input.messageId");
+    }
+    const config = parseFeishuSourceConfig(source);
+    const anchorRaw = await client.getMessage({
+        endpoint: config.endpoint,
+        schemaUrl: config.schemaUrl,
+        auth: config.uxcAuth,
+        messageId,
+    });
+    const anchorMessage = normalizeFeishuMessage(anchorRaw);
+    const chatId = asString(input.chatId) ?? anchorMessage?.chatId ?? null;
+    const warnings = [];
+    let chatWindowMessages = [];
+    if (chatId) {
+        const windowBefore = positiveInteger(input.windowBefore) ?? 5;
+        const windowAfter = positiveInteger(input.windowAfter) ?? 5;
+        try {
+            chatWindowMessages = await fetchFeishuChatWindow({
+                client,
+                config,
+                chatId,
+                anchorMessage,
+                windowBefore,
+                windowAfter,
+            });
+        }
+        catch (error) {
+            warnings.push({
+                code: "chat_window_unavailable",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return {
+        anchorMessage,
+        chatWindowMessages,
+        threadMessages: [],
+        warnings,
+        deliveryHandle: {
+            provider: "feishu",
+            surface: "message_reply",
+            targetRef: messageId,
+            threadRef: anchorMessage?.threadId ?? anchorMessage?.parentId ?? null,
+            replyMode: "reply",
+        },
+    };
+}
+async function listFeishuChats(source, input, client) {
+    const config = parseFeishuSourceConfig(source);
+    const raw = await withFeishuChatDiscoveryError("list_chats", () => client.listChats({
+        endpoint: config.endpoint,
+        schemaUrl: config.schemaUrl,
+        auth: config.uxcAuth,
+        pageSize: boundedPositiveInteger(input.limit, 20, 50),
+        pageToken: asString(input.pageToken) ?? undefined,
+    }));
+    return feishuChatsResult(raw);
+}
+async function searchFeishuChats(source, input, client) {
+    const query = asString(input.query)?.trim();
+    if (!query) {
+        throw new Error("search_chats requires input.query");
+    }
+    const config = parseFeishuSourceConfig(source);
+    const limit = boundedPositiveInteger(input.limit, 20, 50);
+    const raw = await withFeishuChatDiscoveryError("search_chats", () => client.listChats({
+        endpoint: config.endpoint,
+        schemaUrl: config.schemaUrl,
+        auth: config.uxcAuth,
+        pageSize: 50,
+        pageToken: asString(input.pageToken) ?? undefined,
+    }));
+    return feishuChatsResult(raw, searchFeishuChatResults(normalizeFeishuChats(raw), query).slice(0, limit));
+}
+async function getFeishuChat(source, input, client) {
+    const chatId = asString(input.chatId);
+    if (!chatId) {
+        throw new Error("get_chat requires input.chatId");
+    }
+    const config = parseFeishuSourceConfig(source);
+    const raw = await withFeishuChatDiscoveryError("get_chat", () => client.getChat({
+        endpoint: config.endpoint,
+        schemaUrl: config.schemaUrl,
+        auth: config.uxcAuth,
+        chatId,
+    }));
+    return {
+        chat: normalizeFeishuChat(raw),
+        warnings: [],
+    };
+}
+async function withFeishuChatDiscoveryError(operation, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${operation} failed; ensure the configured Feishu UXC auth can read visible chats: ${message}`, { cause: error });
+    }
+}
+function feishuChatsResult(raw, chats = normalizeFeishuChats(raw)) {
+    const pageToken = feishuResponsePageToken(raw);
+    const hasMore = feishuResponseHasMore(raw);
+    return {
+        chats,
+        warnings: [],
+        ...(pageToken ? { pageToken } : {}),
+        ...(hasMore != null ? { hasMore } : {}),
+    };
+}
+function searchFeishuChatResults(chats, query) {
+    const needle = query.trim().toLowerCase();
+    if (!needle) {
+        return [];
+    }
+    return chats.filter((chat) => {
+        const fields = [chat.chatId, chat.name, chat.description, chat.type]
+            .filter((value) => Boolean(value))
+            .map((value) => value.toLowerCase());
+        return fields.some((value) => value.includes(needle));
+    });
+}
+async function listRecentFeishuMessages(source, input, client) {
+    const chatId = asString(input.chatId);
+    if (!chatId) {
+        throw new Error("list_recent_messages requires input.chatId");
+    }
+    const config = parseFeishuSourceConfig(source);
+    const limit = boundedPositiveInteger(input.limit, 20, 50);
+    const raw = await client.listMessages({
+        endpoint: config.endpoint,
+        schemaUrl: config.schemaUrl,
+        auth: config.uxcAuth,
+        chatId,
+        endTime: asString(input.before) ?? undefined,
+        pageToken: asString(input.pageToken) ?? undefined,
+        pageSize: limit,
+        sort: "ByCreateTimeDesc",
+    });
+    return {
+        chatId,
+        messages: normalizeFeishuMessages(raw),
+        warnings: [],
+        ...(feishuResponsePageToken(raw) ? { pageToken: feishuResponsePageToken(raw) } : {}),
+        ...(feishuResponseHasMore(raw) != null ? { hasMore: feishuResponseHasMore(raw) } : {}),
+    };
+}
 function normalizeFeishuBotEvent(source, config, raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         return null;
     }
     const payload = raw;
     const header = asRecord(payload.header);
-    const eventType = asString(payload.event_type) ?? asString(header.event_type);
+    const eventType = asString(payload.event_type) ?? asString(payload.type) ?? asString(header.event_type);
     if (!eventType || !(config.eventTypes ?? exports.DEFAULT_FEISHU_EVENT_TYPES).includes(eventType)) {
         return null;
     }
     const event = asRecord(payload.event);
-    const message = nonEmptyRecord(payload.message) ?? nonEmptyRecord(event.message) ?? {};
-    const sender = nonEmptyRecord(payload.sender) ?? nonEmptyRecord(event.sender) ?? {};
+    const message = nonEmptyRecord(payload.message) ?? nonEmptyRecord(event.message) ?? flatFeishuMessage(payload);
+    const sender = nonEmptyRecord(payload.sender) ?? nonEmptyRecord(event.sender) ?? flatFeishuSender(payload);
     const messageId = asString(message.message_id);
-    const eventId = asString(header.event_id) ?? messageId;
+    const eventId = asString(payload.event_id) ?? asString(header.event_id) ?? messageId;
     const chatId = asString(message.chat_id);
     if (!eventId || !messageId || !chatId) {
         return null;
@@ -148,7 +718,7 @@ function normalizeFeishuBotEvent(source, config, raw) {
     const mentions = extractMentionNames(message.mentions);
     const mentionOpenIds = extractMentionOpenIds(message.mentions);
     const messageType = asString(message.message_type) ?? "unknown";
-    const senderId = asString(asRecord(sender.sender_id).open_id);
+    const senderId = asString(asRecord(sender.sender_id).open_id) ?? asString(sender.sender_id);
     const senderType = asString(sender.sender_type);
     const content = stringifyFeishuMessageContent(messageType, asString(message.content), message.mentions);
     const threadId = asString(message.thread_id) ?? asString(message.root_id);
@@ -191,6 +761,26 @@ function normalizeFeishuBotEvent(source, config, raw) {
         },
     };
 }
+function flatFeishuMessage(payload) {
+    return {
+        message_id: payload.message_id,
+        chat_id: payload.chat_id,
+        chat_type: payload.chat_type,
+        message_type: payload.message_type ?? payload.msg_type,
+        content: payload.content,
+        create_time: payload.create_time,
+        mentions: payload.mentions,
+        thread_id: payload.thread_id,
+        root_id: payload.root_id,
+        parent_id: payload.parent_id,
+    };
+}
+function flatFeishuSender(payload) {
+    return {
+        sender_id: payload.sender_id,
+        sender_type: payload.sender_type,
+    };
+}
 function parseFeishuSourceConfig(source) {
     const config = source.config ?? {};
     return {
@@ -231,6 +821,351 @@ function normalizeDeliveryMessage(payload) {
         content: JSON.stringify({ text: JSON.stringify(payload) }),
     };
 }
+function commonDeliveryInputSchemaProperties() {
+    return {
+        endpoint: { type: "string", minLength: 1 },
+        schemaUrl: { type: "string", minLength: 1 },
+        schema_url: { type: "string", minLength: 1 },
+        uxcAuth: { type: "string", minLength: 1 },
+        auth: { type: "string", minLength: 1 },
+        replyInThread: { type: "boolean" },
+        reply_in_thread: { type: "boolean" },
+        uuid: { type: "string", minLength: 1 },
+    };
+}
+function normalizeFeishuFileMessage(fileKey) {
+    return {
+        msgType: "file",
+        content: JSON.stringify({ file_key: fileKey }),
+    };
+}
+function normalizeFeishuPostMessage(input) {
+    const rawContent = input.content;
+    if (typeof rawContent === "string" && rawContent.trim().length > 0) {
+        return { msgType: "post", content: rawContent };
+    }
+    if (rawContent && typeof rawContent === "object" && !Array.isArray(rawContent)) {
+        return { msgType: "post", content: JSON.stringify(rawContent) };
+    }
+    const paragraphs = normalizePostParagraphs(input);
+    if (paragraphs.length === 0) {
+        throw new Error("send_post requires input.blocks, input.paragraphs, or input.content");
+    }
+    const locale = asString(input.locale) ?? "zh_cn";
+    return {
+        msgType: "post",
+        content: JSON.stringify({
+            [locale]: {
+                title: asString(input.title) ?? "",
+                content: paragraphs,
+            },
+        }),
+    };
+}
+function normalizePostParagraphs(input) {
+    if (Array.isArray(input.paragraphs)) {
+        return input.paragraphs
+            .map((paragraph) => Array.isArray(paragraph) ? normalizePostBlocks(paragraph) : [])
+            .filter((paragraph) => paragraph.length > 0);
+    }
+    if (Array.isArray(input.blocks)) {
+        const paragraph = normalizePostBlocks(input.blocks);
+        return paragraph.length > 0 ? [paragraph] : [];
+    }
+    return [];
+}
+function normalizePostBlocks(blocks) {
+    return blocks.map((block) => normalizePostBlock(asRecord(block))).filter((block) => block !== null);
+}
+function normalizePostBlock(block) {
+    const type = asString(block.type) ?? "text";
+    if (type === "text") {
+        const text = asString(block.text);
+        if (!text) {
+            return null;
+        }
+        return { tag: "text", text };
+    }
+    if (type === "link") {
+        const text = asString(block.text);
+        const url = asString(block.url) ?? asString(block.href);
+        if (!text || !url) {
+            return null;
+        }
+        return { tag: "a", text, href: url };
+    }
+    if (type === "mention") {
+        const openId = asString(block.openId) ?? asString(block.open_id) ?? asString(block.userId) ?? asString(block.user_id);
+        if (!openId) {
+            return null;
+        }
+        return {
+            tag: "at",
+            user_id: openId,
+            ...(asString(block.name) ? { user_name: asString(block.name) } : {}),
+        };
+    }
+    return null;
+}
+function basename(filePath) {
+    const trimmed = filePath.replace(/\/+$/, "");
+    const parts = trimmed.split("/");
+    return parts[parts.length - 1] || "upload.bin";
+}
+function findStringField(value, field) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const record = value;
+    const direct = asString(record[field]);
+    if (direct) {
+        return direct;
+    }
+    for (const child of Object.values(record)) {
+        const found = findStringField(child, field);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
+function feishuFollowSourceConfig(source) {
+    const config = parseFeishuSourceConfig(source);
+    return {
+        ...(config.endpoint && config.endpoint !== exports.FEISHU_OPENAPI_ENDPOINT ? { endpoint: config.endpoint } : {}),
+        ...(config.schemaUrl && config.schemaUrl !== exports.FEISHU_IM_SCHEMA_URL ? { schemaUrl: config.schemaUrl } : {}),
+        ...(config.uxcAuth ? { uxcAuth: config.uxcAuth } : {}),
+        ...(config.eventTypes ? { eventTypes: config.eventTypes } : {}),
+    };
+}
+function normalizeFeishuMessage(raw) {
+    const message = firstFeishuMessage(raw);
+    if (!message) {
+        return null;
+    }
+    const sender = asRecord(message.sender);
+    const messageType = asString(message.msg_type) ?? asString(message.message_type) ?? "unknown";
+    return {
+        messageId: asString(message.message_id) ?? "",
+        chatId: asString(message.chat_id),
+        chatType: asString(message.chat_type),
+        messageType,
+        senderOpenId: senderOpenId(sender),
+        senderType: asString(sender.sender_type) ?? asString(asRecord(sender.id).user_id) ?? null,
+        mentions: extractMentionNames(message.mentions),
+        mentionOpenIds: extractMentionOpenIds(message.mentions),
+        content: stringifyFeishuMessageContent(messageType, messageContentString(message), message.mentions),
+        createdAt: fromUnixMillisString(asString(message.create_time)),
+        threadId: asString(message.thread_id) ?? asString(message.root_id),
+        parentId: asString(message.parent_id),
+        raw: message,
+    };
+}
+function senderOpenId(sender) {
+    const nested = asString(asRecord(sender.id).open_id) ?? asString(asRecord(sender.sender_id).open_id);
+    if (nested) {
+        return nested;
+    }
+    const id = asString(sender.id) ?? asString(sender.sender_id);
+    const idType = asString(sender.id_type);
+    return id && (!idType || idType === "open_id") ? id : null;
+}
+function normalizeFeishuMessages(raw) {
+    const items = feishuMessageItems(raw);
+    return items
+        .map((item) => normalizeFeishuMessage(item))
+        .filter((item) => item !== null);
+}
+function normalizeFeishuChat(raw) {
+    const chat = firstFeishuChat(raw);
+    if (!chat) {
+        return null;
+    }
+    return {
+        chatId: asString(chat.chat_id) ?? "",
+        name: asString(chat.name) ?? asString(chat.chat_name),
+        description: asString(chat.description),
+        type: asString(chat.chat_type) ?? asString(chat.chat_mode) ?? asString(chat.type),
+        memberCount: asNumber(chat.member_count) ?? asNumber(chat.members_count) ?? asNumber(chat.user_count),
+        isBotMember: asBoolean(chat.is_bot_member) ?? asBoolean(chat.bot_member) ?? asBoolean(chat.is_member),
+        raw: chat,
+    };
+}
+function normalizeFeishuChats(raw) {
+    return feishuChatItems(raw)
+        .map((item) => normalizeFeishuChat(item))
+        .filter((item) => item !== null);
+}
+async function fetchFeishuChatWindow(input) {
+    const anchorSeconds = feishuMessageCreateSeconds(input.anchorMessage);
+    const pageSize = Math.max(1, Math.min(input.windowBefore + input.windowAfter + 1, 50));
+    if (!anchorSeconds) {
+        const fallbackRaw = await input.client.listMessages({
+            endpoint: input.config.endpoint,
+            schemaUrl: input.config.schemaUrl,
+            auth: input.config.uxcAuth,
+            chatId: input.chatId,
+            pageSize,
+        });
+        return normalizeFeishuMessages(fallbackRaw);
+    }
+    const beforeRaw = input.windowBefore > 0
+        ? await input.client.listMessages({
+            endpoint: input.config.endpoint,
+            schemaUrl: input.config.schemaUrl,
+            auth: input.config.uxcAuth,
+            chatId: input.chatId,
+            startTime: String(Math.max(0, anchorSeconds - DEFAULT_CONTEXT_BOUND_SECONDS)),
+            endTime: String(anchorSeconds + 1),
+            pageSize: Math.max(1, Math.min(input.windowBefore + 1, 50)),
+            sort: "ByCreateTimeDesc",
+        })
+        : null;
+    const afterRaw = input.windowAfter > 0
+        ? await input.client.listMessages({
+            endpoint: input.config.endpoint,
+            schemaUrl: input.config.schemaUrl,
+            auth: input.config.uxcAuth,
+            chatId: input.chatId,
+            startTime: String(anchorSeconds),
+            endTime: String(anchorSeconds + DEFAULT_CONTEXT_BOUND_SECONDS),
+            pageSize: Math.max(1, Math.min(input.windowAfter + 1, 50)),
+            sort: "ByCreateTimeAsc",
+        })
+        : null;
+    return mergeFeishuMessages([
+        ...(beforeRaw ? normalizeFeishuMessages(beforeRaw) : []),
+        ...(input.anchorMessage ? [input.anchorMessage] : []),
+        ...(afterRaw ? normalizeFeishuMessages(afterRaw) : []),
+    ]);
+}
+function mergeFeishuMessages(messages) {
+    const byId = new Map();
+    for (const message of messages) {
+        if (message.messageId) {
+            byId.set(message.messageId, message);
+        }
+    }
+    return Array.from(byId.values()).sort((left, right) => {
+        const leftTime = feishuMessageCreateMillis(left) ?? 0;
+        const rightTime = feishuMessageCreateMillis(right) ?? 0;
+        return leftTime - rightTime;
+    });
+}
+function feishuMessageCreateSeconds(message) {
+    const millis = feishuMessageCreateMillis(message);
+    return millis == null ? null : Math.floor(millis / 1000);
+}
+function feishuMessageCreateMillis(message) {
+    if (!message) {
+        return null;
+    }
+    const rawMillis = Number(asString(message.raw.create_time));
+    if (Number.isFinite(rawMillis)) {
+        return rawMillis;
+    }
+    if (message.createdAt) {
+        const parsed = Date.parse(message.createdAt);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function firstFeishuMessage(raw) {
+    const items = feishuMessageItems(raw);
+    if (items[0]) {
+        return items[0];
+    }
+    const record = asRecord(raw);
+    if (asString(record.message_id)) {
+        return record;
+    }
+    return null;
+}
+function feishuMessageItems(raw) {
+    const record = asRecord(raw);
+    const data = asRecord(record.data);
+    const nestedData = asRecord(data.data);
+    const items = Array.isArray(nestedData.items)
+        ? nestedData.items
+        : Array.isArray(data.items)
+            ? data.items
+            : Array.isArray(record.items)
+                ? record.items
+                : Array.isArray(raw)
+                    ? raw
+                    : [];
+    return items.map((item) => asRecord(item)).filter((item) => Object.keys(item).length > 0);
+}
+function firstFeishuChat(raw) {
+    const items = feishuChatItems(raw);
+    if (items[0]) {
+        return items[0];
+    }
+    const record = asRecord(raw);
+    const data = asRecord(record.data);
+    const nestedData = asRecord(data.data);
+    if (asString(nestedData.chat_id)) {
+        return nestedData;
+    }
+    if (asString(data.chat_id)) {
+        return data;
+    }
+    if (asString(record.chat_id)) {
+        return record;
+    }
+    return null;
+}
+function feishuChatItems(raw) {
+    const record = asRecord(raw);
+    const data = asRecord(record.data);
+    const nestedData = asRecord(data.data);
+    const items = Array.isArray(nestedData.items)
+        ? nestedData.items
+        : Array.isArray(data.items)
+            ? data.items
+            : Array.isArray(record.items)
+                ? record.items
+                : Array.isArray(raw)
+                    ? raw
+                    : [];
+    return items.map((item) => asRecord(item)).filter((item) => asString(item.chat_id));
+}
+function messageContentString(message) {
+    const body = asRecord(message.body);
+    return asString(body.content) ?? asString(message.content);
+}
+function positiveInteger(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        return null;
+    }
+    return value;
+}
+function boundedPositiveInteger(value, fallback, max) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        return fallback;
+    }
+    return Math.min(value, max);
+}
+function feishuResponsePageToken(raw) {
+    const record = asRecord(raw);
+    const data = asRecord(record.data);
+    const nestedData = asRecord(data.data);
+    return asString(nestedData.page_token)
+        ?? asString(data.page_token)
+        ?? asString(record.page_token);
+}
+function feishuResponseHasMore(raw) {
+    const record = asRecord(raw);
+    const data = asRecord(record.data);
+    const nestedData = asRecord(data.data);
+    if (typeof nestedData.has_more === "boolean") {
+        return nestedData.has_more;
+    }
+    if (typeof data.has_more === "boolean") {
+        return data.has_more;
+    }
+    return typeof record.has_more === "boolean" ? record.has_more : null;
+}
 function extractMentionNames(raw) {
     if (!Array.isArray(raw)) {
         return [];
@@ -269,7 +1204,8 @@ function stringifyFeishuMessageContent(messageType, rawContent, mentions) {
         return rawContent;
     }
     if (messageType === "text") {
-        return asString(asRecord(parsed).text) ?? rawContent;
+        const text = asString(asRecord(parsed).text) ?? rawContent;
+        return replaceMentionKeys(text, mentions);
     }
     if (messageType === "post") {
         const mentionMap = buildMentionMap(mentions);
@@ -303,6 +1239,13 @@ function buildMentionMap(raw) {
     }
     return map;
 }
+function replaceMentionKeys(text, mentions) {
+    let result = text;
+    for (const [key, name] of buildMentionMap(mentions)) {
+        result = result.split(key).join(name);
+    }
+    return result;
+}
 function flattenPostContent(raw, mentionMap) {
     const parsed = asRecord(raw);
     const localeEntries = Object.entries(parsed);
@@ -369,9 +1312,18 @@ function asRecord(value) {
     }
     return value;
 }
+function compactPayload(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
 function asString(value) {
     return typeof value === "string" ? value : null;
 }
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : null;
+}
 function asStringArray(value) {
     if (!Array.isArray(value)) {
         return null;
@@ -380,3 +1332,50 @@ function asStringArray(value) {
         .map((item) => asString(item))
         .filter((item) => Boolean(item));
 }
+function ensureFeishuBotSchemaFile() {
+    const body = JSON.stringify(FEISHU_BOT_OPENAPI_SCHEMA);
+    (0, node_fs_1.writeFileSync)(FEISHU_BOT_SCHEMA_FILE, body, "utf8");
+    return FEISHU_BOT_SCHEMA_FILE;
+}
+const FEISHU_BOT_OPENAPI_SCHEMA = {
+    openapi: "3.0.3",
+    info: {
+        title: "Feishu Bot Info",
+        version: "1.0.0",
+    },
+    servers: [
+        {
+            url: exports.FEISHU_OPENAPI_ENDPOINT,
+        },
+    ],
+    // Feishu's docs site does not currently expose this as a stable
+    // machine-readable OpenAPI document to UXC, so keep the tiny operation
+    // schema needed for bot self-identification close to the adapter.
+    paths: {
+        "/bot/v3/info": {
+            get: {
+                operationId: "get:/bot/v3/info",
+                summary: "Get bot information for the current app",
+                responses: {
+                    "200": {
+                        description: "OK",
+                    },
+                },
+                security: [
+                    {
+                        bearerAuth: [],
+                    },
+                ],
+            },
+        },
+    },
+    components: {
+        securitySchemes: {
+            bearerAuth: {
+                type: "http",
+                scheme: "bearer",
+                bearerFormat: "tenant_access_token",
+            },
+        },
+    },
+};