@tobeyoureyes/feishu 1.0.0

package/src/context.ts

@@ -0,0 +1,292 @@
+/**
+ * Feishu message context builder
+ *
+ * Converts inbound Feishu messages to the standard OpenClaw message context format.
+ * Uses the PluginRuntime API (core.channel.*) for all core functionality.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { getFeishuRuntime } from "./runtime.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+import type { FeishuInboundMessage } from "./webhook.js";
+import type { HistoryEntry } from "./history.js";
+
+/**
+ * Feishu message context - returned by buildFeishuMessageContext
+ */
+export interface FeishuMessageContext {
+  ctxPayload: Record<string, unknown>;
+  message: FeishuInboundMessage;
+  account: ResolvedFeishuAccount;
+  chatId: string;
+  isGroup: boolean;
+  route: {
+    agentId?: string;
+    sessionKey: string;
+    accountId: string;
+    mainSessionKey?: string;
+  };
+  sendTyping: () => Promise<void>;
+}
+
+export interface BuildFeishuMessageContextParams {
+  message: FeishuInboundMessage;
+  account: ResolvedFeishuAccount;
+  cfg: OpenClawConfig;
+  botOpenId?: string;
+  sendTyping?: () => Promise<void>;
+  /** Pending group history entries for context */
+  pendingHistory?: HistoryEntry[];
+}
+
+/**
+ * Check if bot was mentioned in the message
+ */
+function isBotMentioned(message: FeishuInboundMessage, botOpenId?: string): boolean {
+  if (!botOpenId || !message.mentions) {
+    return false;
+  }
+  return message.mentions.some((m) => m.id === botOpenId);
+}
+
+/**
+ * Strip bot mention from message text
+ */
+function stripBotMention(text: string, mentions?: FeishuInboundMessage["mentions"]): string {
+  if (!mentions || mentions.length === 0) {
+    return text;
+  }
+
+  let result = text;
+  for (const mention of mentions) {
+    // Remove @_user_X placeholder and surrounding whitespace
+    const placeholder = mention.key;
+    result = result.replace(new RegExp(`\\s*${placeholder}\\s*`, "g"), " ").trim();
+  }
+  return result;
+}
+
+/**
+ * Build sender label for envelope
+ */
+function buildSenderLabel(message: FeishuInboundMessage): string {
+  return message.senderOpenId ?? message.senderId;
+}
+
+/**
+ * Build conversation label
+ */
+function buildConversationLabel(message: FeishuInboundMessage, isGroup: boolean): string {
+  if (isGroup) {
+    return `group:${message.chatId}`;
+  }
+  return buildSenderLabel(message);
+}
+
+/**
+ * Format a history entry for display in context
+ */
+function formatHistoryEntry(entry: HistoryEntry): string {
+  return `[${entry.sender}]: ${entry.body}`;
+}
+
+/**
+ * Build history context string from entries
+ */
+function buildHistoryContext(entries: HistoryEntry[], currentMessage: string): string {
+  if (entries.length === 0) {
+    return currentMessage;
+  }
+
+  const historyLines = entries.map(formatHistoryEntry);
+  return `[Recent conversation context]\n${historyLines.join("\n")}\n[/Recent conversation context]\n\n${currentMessage}`;
+}
+
+/**
+ * Build Feishu message context for dispatch
+ *
+ * Uses PluginRuntime API (core.channel.*) for all core functionality:
+ * - core.channel.routing.resolveAgentRoute
+ * - core.channel.session.resolveStorePath
+ * - core.channel.session.readSessionUpdatedAt
+ * - core.channel.reply.resolveEnvelopeFormatOptions
+ * - core.channel.reply.formatAgentEnvelope
+ * - core.channel.reply.finalizeInboundContext
+ * - core.channel.session.recordInboundSession
+ */
+export async function buildFeishuMessageContext(
+  params: BuildFeishuMessageContextParams,
+): Promise<FeishuMessageContext | null> {
+  const { message, account, cfg, botOpenId, sendTyping, pendingHistory } = params;
+  const core = getFeishuRuntime();
+
+  const isGroup = message.chatType === "group";
+  const peerId = message.chatId;
+
+  // Resolve agent route using core API
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "feishu",
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "dm",
+      id: peerId,
+    },
+  });
+
+  const sessionKey = route.sessionKey;
+
+  // DM policy check
+  if (!isGroup) {
+    const dmPolicy = account.config.dmPolicy ?? "pairing";
+    if (dmPolicy === "disabled") {
+      if (core.logging.shouldLogVerbose()) {
+        core.logging.getChildLogger({ module: "feishu" }).debug("blocked DM (dmPolicy=disabled)");
+      }
+      return null;
+    }
+
+    if (dmPolicy !== "open") {
+      const allowFrom = account.config.allowFrom ?? [];
+      const senderId = message.senderOpenId ?? message.senderId;
+      const allowed = allowFrom.length === 0 || allowFrom.includes(senderId);
+      if (!allowed && dmPolicy === "allowlist") {
+        if (core.logging.shouldLogVerbose()) {
+          core.logging.getChildLogger({ module: "feishu" }).debug(`blocked unauthorized DM sender ${senderId}`);
+        }
+        return null;
+      }
+      // pairing mode would need additional handling
+    }
+  }
+
+  // Group mention gating
+  if (isGroup) {
+    const groupPolicy = account.config.groupPolicy ?? "allowlist";
+    if (groupPolicy === "disabled") {
+      if (core.logging.shouldLogVerbose()) {
+        core.logging.getChildLogger({ module: "feishu" }).debug("blocked group message (groupPolicy=disabled)");
+      }
+      return null;
+    }
+
+    const requireMention = account.requireMention;
+    const wasMentioned = isBotMentioned(message, botOpenId);
+
+    // Simple mention gating: if requireMention is true and bot was not mentioned, skip
+    if (requireMention && !wasMentioned) {
+      if (core.logging.shouldLogVerbose()) {
+        core.logging.getChildLogger({ module: "feishu" }).debug("skipping group message (no mention)");
+      }
+      return null;
+    }
+  }
+
+  // Build message body
+  const rawBody = message.displayText ?? message.text ?? "";
+  const bodyForAgent = isGroup ? stripBotMention(rawBody, message.mentions) : rawBody;
+
+  const senderLabel = buildSenderLabel(message);
+  const conversationLabel = buildConversationLabel(message, isGroup);
+
+  // Resolve store path and get previous timestamp using core API
+  const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey,
+  });
+
+  // Format envelope with previous timestamp for elapsed time display
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+  const baseBody = core.channel.reply.formatAgentEnvelope({
+    channel: "Feishu",
+    from: conversationLabel,
+    timestamp: message.createTime,
+    previousTimestamp,
+    body: bodyForAgent,
+    envelope: envelopeOptions,
+  });
+
+  // Build reply context
+  const replySuffix = message.replyToBody
+    ? `\n\n[Replying to ${message.replyToSenderId ?? "unknown"}]\n${message.replyToBody}\n[/Replying]`
+    : "";
+
+  const messageWithReply = baseBody + replySuffix;
+
+  // Build group history context if available
+  let combinedBody: string;
+  if (isGroup && pendingHistory && pendingHistory.length > 0) {
+    combinedBody = buildHistoryContext(pendingHistory, messageWithReply);
+  } else {
+    combinedBody = messageWithReply;
+  }
+
+  // Build context payload using core API
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: combinedBody,
+    RawBody: rawBody,
+    CommandBody: bodyForAgent,
+    From: isGroup ? `feishu:group:${message.chatId}` : `feishu:${message.chatId}`,
+    To: `feishu:${message.chatId}`,
+    SessionKey: sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: conversationLabel,
+    SenderName: senderLabel,
+    SenderId: message.senderOpenId ?? message.senderId,
+    Provider: "feishu" as const,
+    Surface: "feishu" as const,
+    MessageSid: message.messageId,
+    ReplyToId: message.replyToId,
+    ReplyToBody: message.replyToBody,
+    ReplyToSender: message.replyToSenderId,
+    Timestamp: message.createTime,
+    WasMentioned: isGroup ? isBotMentioned(message, botOpenId) : undefined,
+    MediaPath: message.mediaPath,
+    MediaType: message.mediaType,
+    MediaUrl: message.mediaPath,
+    OriginatingChannel: "feishu" as const,
+    OriginatingTo: `feishu:${message.chatId}`,
+  });
+
+  // Record session using core API
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: (ctxPayload as { SessionKey?: string }).SessionKey ?? sessionKey,
+    ctx: ctxPayload,
+    updateLastRoute: !isGroup
+      ? {
+          sessionKey: route.mainSessionKey ?? sessionKey,
+          channel: "feishu",
+          to: message.chatId,
+          accountId: route.accountId,
+        }
+      : undefined,
+    onRecordError: (err) => {
+      if (core.logging.shouldLogVerbose()) {
+        core.logging.getChildLogger({ module: "feishu" }).debug(`failed updating session meta: ${String(err)}`);
+      }
+    },
+  });
+
+  if (core.logging.shouldLogVerbose()) {
+    const preview = combinedBody.slice(0, 200).replace(/\n/g, "\\n");
+    core.logging.getChildLogger({ module: "feishu" }).debug(
+      `inbound: chatId=${message.chatId} from=${(ctxPayload as { From?: string }).From} len=${combinedBody.length} preview="${preview}"`,
+    );
+  }
+
+  return {
+    ctxPayload,
+    message,
+    account,
+    chatId: message.chatId,
+    isGroup,
+    route,
+    sendTyping: sendTyping ?? (async () => {}),
+  };
+}

package/src/dedupe.ts

@@ -0,0 +1,85 @@
+/**
+ * Feishu message deduplication module
+ *
+ * Provides LRU-based deduplication to prevent processing duplicate messages,
+ * which can occur due to WebSocket reconnections or webhook retries.
+ */
+
+export interface DedupeCache {
+  /** Check if a message has already been processed */
+  isProcessed(messageId: string): boolean;
+  /** Mark a message as processed */
+  markProcessed(messageId: string): void;
+  /** Get the current size of the cache */
+  size(): number;
+  /** Clear all entries */
+  clear(): void;
+}
+
+export interface DedupeCacheOptions {
+  /** Maximum number of message IDs to track (default: 1000) */
+  maxSize?: number;
+  /** Cleanup when reaching this threshold (default: 800) */
+  cleanupThreshold?: number;
+}
+
+/**
+ * Create a deduplication cache for Feishu messages
+ *
+ * Uses a Set with LRU-like cleanup to track processed message IDs.
+ * When the cache reaches maxSize, it removes the oldest entries
+ * down to cleanupThreshold.
+ *
+ * @example
+ * ```typescript
+ * const dedupe = createFeishuDedupeCache();
+ *
+ * if (dedupe.isProcessed(messageId)) {
+ *   return; // Skip duplicate
+ * }
+ * dedupe.markProcessed(messageId);
+ * // Process message...
+ * ```
+ */
+export function createFeishuDedupeCache(options: DedupeCacheOptions = {}): DedupeCache {
+  const { maxSize = 1000, cleanupThreshold = 800 } = options;
+
+  const processedMessages = new Set<string>();
+
+  return {
+    isProcessed(messageId: string): boolean {
+      return processedMessages.has(messageId);
+    },
+
+    markProcessed(messageId: string): void {
+      // LRU-like cleanup: remove oldest entries when reaching max size
+      if (processedMessages.size >= maxSize) {
+        const toDelete = processedMessages.size - cleanupThreshold;
+        const iterator = processedMessages.values();
+
+        for (let i = 0; i < toDelete; i++) {
+          const value = iterator.next().value;
+          if (value) {
+            processedMessages.delete(value);
+          }
+        }
+      }
+
+      processedMessages.add(messageId);
+    },
+
+    size(): number {
+      return processedMessages.size;
+    },
+
+    clear(): void {
+      processedMessages.clear();
+    },
+  };
+}
+
+/**
+ * Default deduplication cache configuration
+ */
+export const DEFAULT_DEDUPE_MAX_SIZE = 1000;
+export const DEFAULT_DEDUPE_CLEANUP_THRESHOLD = 800;

package/src/dispatch.ts

@@ -0,0 +1,185 @@
+/**
+ * Feishu message dispatch module
+ *
+ * Handles dispatching messages to the AI agent and delivering replies.
+ * Uses the PluginRuntime API (core.channel.*) for all core functionality.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { getFeishuRuntime } from "./runtime.js";
+import type { FeishuMessageContext } from "./context.js";
+import type { ResolvedFeishuAccount, FeishuRenderMode } from "./types.js";
+import * as api from "./api.js";
+
+/**
+ * Reply payload structure
+ */
+export interface ReplyPayload {
+  text: string;
+  replyToId?: string;
+  mediaUrl?: string;
+}
+
+/**
+ * Dispatch options
+ */
+export interface DispatchFeishuMessageParams {
+  /** Message context from buildFeishuMessageContext */
+  context: FeishuMessageContext;
+  /** OpenClaw configuration */
+  cfg: OpenClawConfig;
+  /** Callback for sending text replies */
+  onSendReply?: (params: {
+    text: string;
+    replyToId?: string;
+    renderMode?: FeishuRenderMode;
+  }) => Promise<{ ok: boolean; messageId?: string; error?: string }>;
+  /** Callback for sending media */
+  onSendMedia?: (params: {
+    text?: string;
+    mediaUrl: string;
+    replyToId?: string;
+  }) => Promise<{ ok: boolean; messageId?: string; error?: string }>;
+  /** Callback when reply starts */
+  onReplyStart?: () => void;
+  /** Callback when dispatch is idle */
+  onIdle?: () => void;
+}
+
+/**
+ * Dispatch result
+ */
+export interface DispatchResult {
+  /** Whether a final reply was queued/sent */
+  queuedFinal: boolean;
+  /** Reply counts */
+  counts: {
+    final: number;
+    interim: number;
+  };
+}
+
+/**
+ * Dispatch Feishu message to AI agent and deliver replies
+ *
+ * Uses PluginRuntime API (core.channel.*) for dispatch:
+ * - core.channel.reply.createReplyDispatcherWithTyping
+ * - core.channel.reply.resolveHumanDelayConfig
+ * - core.channel.reply.dispatchReplyFromConfig
+ * - core.channel.text.resolveTextChunkLimit
+ * - core.channel.text.resolveMarkdownTableMode
+ */
+export async function dispatchFeishuMessage(
+  params: DispatchFeishuMessageParams,
+): Promise<DispatchResult> {
+  const { context, cfg, onSendReply, onSendMedia, onReplyStart, onIdle } = params;
+  const core = getFeishuRuntime();
+  const logger = core.logging.getChildLogger({ module: "feishu" });
+
+  const { ctxPayload, account, chatId, route } = context;
+
+  // Get text configuration
+  const _textLimit = core.channel.text.resolveTextChunkLimit(cfg, "feishu");
+  const _tableMode = core.channel.text.resolveMarkdownTableMode({
+    cfg,
+    channel: "feishu",
+    accountId: route.accountId,
+  });
+
+  // Create dispatcher with typing indicator support
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+      deliver: async (payload) => {
+        const text = payload.text ?? "";
+        const mediaUrl = payload.mediaUrl;
+
+        logger.info(`deliver called: text=${text.slice(0, 100)} mediaUrl=${mediaUrl}`);
+
+        if (mediaUrl && onSendMedia) {
+          logger.info(`sending media to ${context.message.messageId}`);
+          const result = await onSendMedia({
+            text,
+            mediaUrl,
+            replyToId: context.message.messageId,
+          });
+          logger.info(`media send result: ${JSON.stringify(result)}`);
+        } else if (text && onSendReply) {
+          // Determine render mode based on content
+          const renderMode = api.shouldUseCardRendering(text) ? "card" : account.renderMode;
+          logger.info(`sending reply to ${context.message.messageId} renderMode=${renderMode}`);
+          const result = await onSendReply({
+            text,
+            replyToId: context.message.messageId,
+            renderMode,
+          });
+          logger.info(`reply send result: ${JSON.stringify(result)}`);
+        } else {
+          logger.warn(`deliver called but no handler: text=${!!text} onSendReply=${!!onSendReply}`);
+        }
+      },
+      onError: (err, info) => {
+        logger.error(`${info.kind} reply failed: ${String(err)}`);
+      },
+      onReplyStart,
+      onIdle,
+    });
+
+  try {
+    // Dispatch to agent
+    const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions,
+    });
+
+    markDispatchIdle();
+
+    if (queuedFinal && core.logging.shouldLogVerbose()) {
+      logger.debug(`delivered ${counts.final} reply${counts.final === 1 ? "" : "ies"} to ${chatId}`);
+    }
+
+    return { queuedFinal, counts };
+  } catch (err) {
+    markDispatchIdle();
+    logger.error(`dispatch failed: ${String(err)}`);
+    return { queuedFinal: false, counts: { final: 0, interim: 0 } };
+  }
+}
+
+/**
+ * Create default reply sender using Feishu API
+ */
+export function createDefaultReplySender(account: ResolvedFeishuAccount) {
+  return async (params: {
+    text: string;
+    replyToId?: string;
+    renderMode?: FeishuRenderMode;
+  }) => {
+    if (!params.replyToId) {
+      return { ok: false, error: "Missing replyToId" };
+    }
+    return api.replyMessage(account, params.replyToId, params.text, {
+      renderMode: params.renderMode,
+    });
+  };
+}
+
+/**
+ * Create default media sender using Feishu API
+ */
+export function createDefaultMediaSender(account: ResolvedFeishuAccount) {
+  return async (params: {
+    text?: string;
+    mediaUrl: string;
+    replyToId?: string;
+  }) => {
+    if (!params.replyToId) {
+      return { ok: false, error: "Missing replyToId" };
+    }
+    // For now, send media URL as text
+    const text = params.text ? `${params.text}\n\n${params.mediaUrl}` : params.mediaUrl;
+    return api.replyMessage(account, params.replyToId, text);
+  };
+}

package/src/history.ts

@@ -0,0 +1,130 @@
+/**
+ * Feishu group chat history management module
+ *
+ * Manages pending message history for group chats to provide context
+ * when the bot is mentioned. Messages are accumulated until the bot
+ * responds, then cleared.
+ */
+
+/**
+ * History entry for a group chat message
+ */
+export interface HistoryEntry {
+  /** Sender identifier (open_id or user_id) */
+  sender: string;
+  /** Message body text */
+  body: string;
+  /** Message timestamp (Unix milliseconds) */
+  timestamp: number;
+  /** Feishu message ID */
+  messageId: string;
+}
+
+export interface GroupHistoryManager {
+  /** Record a message to group history */
+  record(chatId: string, entry: HistoryEntry): void;
+  /** Get pending history entries for a group */
+  get(chatId: string): HistoryEntry[];
+  /** Clear history after bot replies */
+  clear(chatId: string): void;
+  /** Get number of groups being tracked */
+  groupCount(): number;
+  /** Clear all history */
+  clearAll(): void;
+}
+
+export interface GroupHistoryManagerOptions {
+  /** Maximum messages to keep per group (default: 10) */
+  historyLimit?: number;
+  /** Maximum groups to track (default: 100) */
+  maxGroups?: number;
+}
+
+/**
+ * Create a group history manager for Feishu
+ *
+ * Tracks pending messages in group chats that haven't triggered a bot response.
+ * When the bot is mentioned, the history provides context for the conversation.
+ * After the bot replies, the history is cleared.
+ *
+ * Uses LRU eviction for groups when maxGroups is exceeded.
+ *
+ * @example
+ * ```typescript
+ * const history = createGroupHistoryManager();
+ *
+ * // Record messages that don't trigger the bot
+ * history.record(chatId, { sender, body, timestamp, messageId });
+ *
+ * // When bot is mentioned, get history for context
+ * const pendingHistory = history.get(chatId);
+ *
+ * // After bot replies, clear the history
+ * history.clear(chatId);
+ * ```
+ */
+export function createGroupHistoryManager(
+  options: GroupHistoryManagerOptions = {},
+): GroupHistoryManager {
+  const { historyLimit = 10, maxGroups = 100 } = options;
+
+  const groupHistories = new Map<string, HistoryEntry[]>();
+
+  return {
+    record(chatId: string, entry: HistoryEntry): void {
+      // LRU eviction: remove oldest groups when exceeding limit
+      if (groupHistories.size > maxGroups) {
+        const keysToDelete = groupHistories.size - maxGroups;
+        const iterator = groupHistories.keys();
+
+        for (let i = 0; i < keysToDelete; i++) {
+          const key = iterator.next().value;
+          if (key) {
+            groupHistories.delete(key);
+          }
+        }
+      }
+
+      // Get or create history for this chat
+      let history = groupHistories.get(chatId);
+      if (!history) {
+        history = [];
+        groupHistories.set(chatId, history);
+      }
+
+      // Add entry and trim to limit (FIFO)
+      history.push(entry);
+      while (history.length > historyLimit) {
+        history.shift();
+      }
+
+      // Refresh insertion order for LRU (move to end)
+      if (groupHistories.has(chatId)) {
+        groupHistories.delete(chatId);
+        groupHistories.set(chatId, history);
+      }
+    },
+
+    get(chatId: string): HistoryEntry[] {
+      return groupHistories.get(chatId) ?? [];
+    },
+
+    clear(chatId: string): void {
+      groupHistories.set(chatId, []);
+    },
+
+    groupCount(): number {
+      return groupHistories.size;
+    },
+
+    clearAll(): void {
+      groupHistories.clear();
+    },
+  };
+}
+
+/**
+ * Default history management configuration
+ */
+export const DEFAULT_GROUP_HISTORY_LIMIT = 10;
+export const DEFAULT_MAX_GROUPS = 100;