@gakr-gakr/feishu 0.1.0

package/src/config-schema.ts

@@ -0,0 +1,335 @@
+import { normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { z } from "zod";
+export { z };
+import { buildSecretInputSchema, hasConfiguredSecretInput } from "./secret-input.js";
+
+const ChannelActionsSchema = z
+  .object({
+    reactions: z.boolean().optional(),
+  })
+  .strict()
+  .optional();
+
+const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
+const GroupPolicySchema = z.union([
+  z.enum(["open", "allowlist", "disabled"]),
+  z.literal("allowall").transform(() => "open" as const),
+]);
+const FeishuDomainSchema = z.union([
+  z.enum(["feishu", "lark"]),
+  z.string().url().startsWith("https://"),
+]);
+const FeishuConnectionModeSchema = z.enum(["websocket", "webhook"]);
+const TtsOverrideSchema = z
+  .object({
+    auto: z.enum(["off", "always", "inbound", "tagged"]).optional(),
+    enabled: z.boolean().optional(),
+    mode: z.enum(["final", "all"]).optional(),
+    provider: z.string().optional(),
+    persona: z.string().optional(),
+    personas: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    summaryModel: z.string().optional(),
+    modelOverrides: z.record(z.string(), z.unknown()).optional(),
+    providers: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    prefsPath: z.string().optional(),
+    maxTextLength: z.number().int().min(1).optional(),
+    timeoutMs: z.number().int().min(1000).max(120000).optional(),
+  })
+  .strict()
+  .optional();
+
+const ToolPolicySchema = z
+  .object({
+    allow: z.array(z.string()).optional(),
+    deny: z.array(z.string()).optional(),
+  })
+  .strict()
+  .optional();
+
+const DmConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict()
+  .optional();
+
+const MarkdownConfigSchema = z
+  .object({
+    mode: z.enum(["native", "escape", "strip"]).optional(),
+    tableMode: z.enum(["native", "ascii", "simple"]).optional(),
+  })
+  .strict()
+  .optional();
+
+// Message render mode: auto (default) = detect markdown, raw = plain text, card = always card
+const RenderModeSchema = z.enum(["auto", "raw", "card"]).optional();
+
+// Streaming card mode: when enabled, card replies use Feishu's Card Kit streaming API
+// for incremental text display with a "Thinking..." placeholder
+const StreamingModeSchema = z.boolean().optional();
+const BlockStreamingSchema = z.boolean().optional();
+
+const BlockStreamingCoalesceSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    minDelayMs: z.number().int().positive().optional(),
+    maxDelayMs: z.number().int().positive().optional(),
+  })
+  .strict()
+  .optional();
+
+const ChannelHeartbeatVisibilitySchema = z
+  .object({
+    visibility: z.enum(["visible", "hidden"]).optional(),
+    intervalMs: z.number().int().positive().optional(),
+  })
+  .strict()
+  .optional();
+
+/**
+ * Dynamic agent creation configuration.
+ * When enabled, a new agent is created for each unique DM user.
+ */
+const DynamicAgentCreationSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    workspaceTemplate: z.string().optional(),
+    agentDirTemplate: z.string().optional(),
+    maxAgents: z.number().int().positive().optional(),
+  })
+  .strict()
+  .optional();
+
+/**
+ * Feishu tools configuration.
+ * Controls which tool categories are enabled.
+ *
+ * Dependencies:
+ * - wiki requires doc (wiki content is edited via doc tools)
+ * - perm can work independently but is typically used with drive
+ */
+const FeishuToolsConfigSchema = z
+  .object({
+    doc: z.boolean().optional(), // Document operations (default: true)
+    chat: z.boolean().optional(), // Chat info + member query operations (default: true)
+    wiki: z.boolean().optional(), // Knowledge base operations (default: true, requires doc)
+    drive: z.boolean().optional(), // Cloud storage operations (default: true)
+    perm: z.boolean().optional(), // Permission management (default: false, sensitive)
+    scopes: z.boolean().optional(), // App scopes diagnostic (default: true)
+  })
+  .strict()
+  .optional();
+
+/**
+ * Group session scope for routing Feishu group messages.
+ * - "group" (default): one session per group chat
+ * - "group_sender": one session per (group + sender)
+ * - "group_topic": one session per group topic thread (falls back to group if no topic)
+ * - "group_topic_sender": one session per (group + topic thread + sender),
+ *   falls back to (group + sender) if no topic
+ */
+const GroupSessionScopeSchema = z
+  .enum(["group", "group_sender", "group_topic", "group_topic_sender"])
+  .optional();
+
+/**
+ * @deprecated Use groupSessionScope instead.
+ *
+ * Topic session isolation mode for group chats.
+ * - "disabled" (default): All messages in a group share one session
+ * - "enabled": Messages in different topics get separate sessions
+ *
+ * Topic routing uses Feishu topic-group `thread_id` when the event identifies a
+ * native topic group, and keeps `root_id` precedence for normal groups so
+ * reply-created threads stay on the initiating message session.
+ */
+const TopicSessionModeSchema = z.enum(["disabled", "enabled"]).optional();
+const ReactionNotificationModeSchema = z.enum(["off", "own", "all"]).optional();
+
+/**
+ * Reply-in-thread mode for group chats.
+ * - "disabled" (default): Bot replies are normal inline replies
+ * - "enabled": Bot replies create or continue a Feishu topic thread
+ *
+ * When enabled, the Feishu reply API is called with `reply_in_thread: true`,
+ * causing the reply to appear as a topic (话题) under the original message.
+ */
+const ReplyInThreadSchema = z.enum(["disabled", "enabled"]).optional();
+
+export const FeishuGroupSchema = z
+  .object({
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema,
+    skills: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    systemPrompt: z.string().optional(),
+    groupSessionScope: GroupSessionScopeSchema,
+    topicSessionMode: TopicSessionModeSchema,
+    replyInThread: ReplyInThreadSchema,
+  })
+  .strict();
+
+const FeishuSharedConfigShape = {
+  webhookHost: z.string().optional(),
+  webhookPort: z.number().int().positive().optional(),
+  capabilities: z.array(z.string()).optional(),
+  markdown: MarkdownConfigSchema,
+  configWrites: z.boolean().optional(),
+  dmPolicy: DmPolicySchema.optional(),
+  allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  groupPolicy: GroupPolicySchema.optional(),
+  groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  groupSenderAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  requireMention: z.boolean().optional(),
+  groups: z.record(z.string(), FeishuGroupSchema.optional()).optional(),
+  historyLimit: z.number().int().min(0).optional(),
+  dmHistoryLimit: z.number().int().min(0).optional(),
+  dms: z.record(z.string(), DmConfigSchema).optional(),
+  textChunkLimit: z.number().int().positive().optional(),
+  chunkMode: z.enum(["length", "newline"]).optional(),
+  blockStreaming: BlockStreamingSchema,
+  blockStreamingCoalesce: BlockStreamingCoalesceSchema,
+  mediaMaxMb: z.number().positive().optional(),
+  httpTimeoutMs: z.number().int().positive().max(300_000).optional(),
+  heartbeat: ChannelHeartbeatVisibilitySchema,
+  renderMode: RenderModeSchema,
+  streaming: StreamingModeSchema,
+  tools: FeishuToolsConfigSchema,
+  actions: ChannelActionsSchema,
+  replyInThread: ReplyInThreadSchema,
+  reactionNotifications: ReactionNotificationModeSchema,
+  typingIndicator: z.boolean().optional(),
+  resolveSenderNames: z.boolean().optional(),
+  tts: TtsOverrideSchema,
+};
+
+/**
+ * Per-account configuration.
+ * All fields are optional - missing fields inherit from top-level config.
+ */
+export const FeishuAccountConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    name: z.string().optional(), // Display name for this account
+    appId: z.string().optional(),
+    appSecret: buildSecretInputSchema().optional(),
+    encryptKey: buildSecretInputSchema().optional(),
+    verificationToken: buildSecretInputSchema().optional(),
+    domain: FeishuDomainSchema.optional(),
+    connectionMode: FeishuConnectionModeSchema.optional(),
+    webhookPath: z.string().optional(),
+    ...FeishuSharedConfigShape,
+    groupSessionScope: GroupSessionScopeSchema,
+    topicSessionMode: TopicSessionModeSchema,
+  })
+  .strict();
+
+export const FeishuConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    defaultAccount: z.string().optional(),
+    // Top-level credentials (backward compatible for single-account mode)
+    appId: z.string().optional(),
+    appSecret: buildSecretInputSchema().optional(),
+    encryptKey: buildSecretInputSchema().optional(),
+    verificationToken: buildSecretInputSchema().optional(),
+    domain: FeishuDomainSchema.optional().default("feishu"),
+    connectionMode: FeishuConnectionModeSchema.optional().default("websocket"),
+    webhookPath: z.string().optional().default("/feishu/events"),
+    ...FeishuSharedConfigShape,
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    reactionNotifications: ReactionNotificationModeSchema.optional().default("own"),
+    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+    requireMention: z.boolean().optional(),
+    groupSessionScope: GroupSessionScopeSchema,
+    topicSessionMode: TopicSessionModeSchema,
+    // Dynamic agent creation for DM users
+    dynamicAgentCreation: DynamicAgentCreationSchema,
+    // Optimization flags
+    typingIndicator: z.boolean().optional().default(true),
+    resolveSenderNames: z.boolean().optional().default(true),
+    // Multi-account configuration
+    accounts: z.record(z.string(), FeishuAccountConfigSchema.optional()).optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const defaultAccount = value.defaultAccount?.trim();
+    if (defaultAccount && value.accounts && Object.keys(value.accounts).length > 0) {
+      const normalizedDefaultAccount = normalizeAccountId(defaultAccount);
+      if (!Object.prototype.hasOwnProperty.call(value.accounts, normalizedDefaultAccount)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["defaultAccount"],
+          message: `channels.feishu.defaultAccount="${defaultAccount}" does not match a configured account key`,
+        });
+      }
+    }
+
+    const defaultConnectionMode = value.connectionMode ?? "websocket";
+    const defaultVerificationTokenConfigured = hasConfiguredSecretInput(value.verificationToken);
+    const defaultEncryptKeyConfigured = hasConfiguredSecretInput(value.encryptKey);
+    if (defaultConnectionMode === "webhook") {
+      if (!defaultVerificationTokenConfigured) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["verificationToken"],
+          message:
+            'channels.feishu.connectionMode="webhook" requires channels.feishu.verificationToken',
+        });
+      }
+      if (!defaultEncryptKeyConfigured) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["encryptKey"],
+          message: 'channels.feishu.connectionMode="webhook" requires channels.feishu.encryptKey',
+        });
+      }
+    }
+
+    for (const [accountId, account] of Object.entries(value.accounts ?? {})) {
+      if (!account) {
+        continue;
+      }
+      const accountConnectionMode = account.connectionMode ?? defaultConnectionMode;
+      if (accountConnectionMode !== "webhook") {
+        continue;
+      }
+      const accountVerificationTokenConfigured =
+        hasConfiguredSecretInput(account.verificationToken) || defaultVerificationTokenConfigured;
+      const accountEncryptKeyConfigured =
+        hasConfiguredSecretInput(account.encryptKey) || defaultEncryptKeyConfigured;
+      if (!accountVerificationTokenConfigured) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["accounts", accountId, "verificationToken"],
+          message:
+            `channels.feishu.accounts.${accountId}.connectionMode="webhook" requires ` +
+            "a verificationToken (account-level or top-level)",
+        });
+      }
+      if (!accountEncryptKeyConfigured) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["accounts", accountId, "encryptKey"],
+          message:
+            `channels.feishu.accounts.${accountId}.connectionMode="webhook" requires ` +
+            "an encryptKey (account-level or top-level)",
+        });
+      }
+    }
+
+    if (value.dmPolicy === "open") {
+      const allowFrom = value.allowFrom ?? [];
+      const hasWildcard = allowFrom.some((entry) => String(entry).trim() === "*");
+      if (!hasWildcard) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["allowFrom"],
+          message:
+            'channels.feishu.dmPolicy="open" requires channels.feishu.allowFrom to include "*"',
+        });
+      }
+    }
+  });

package/src/conversation-id.ts

@@ -0,0 +1,199 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+
+export type FeishuGroupSessionScope =
+  | "group"
+  | "group_sender"
+  | "group_topic"
+  | "group_topic_sender";
+
+function normalizeText(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+export function buildFeishuConversationId(params: {
+  chatId: string;
+  scope: FeishuGroupSessionScope;
+  senderOpenId?: string;
+  topicId?: string;
+}): string {
+  const chatId = normalizeText(params.chatId) ?? "unknown";
+  const senderOpenId = normalizeText(params.senderOpenId);
+  const topicId = normalizeText(params.topicId);
+
+  switch (params.scope) {
+    case "group_sender":
+      return senderOpenId ? `${chatId}:sender:${senderOpenId}` : chatId;
+    case "group_topic":
+      return topicId ? `${chatId}:topic:${topicId}` : chatId;
+    case "group_topic_sender":
+      if (topicId && senderOpenId) {
+        return `${chatId}:topic:${topicId}:sender:${senderOpenId}`;
+      }
+      if (topicId) {
+        return `${chatId}:topic:${topicId}`;
+      }
+      return senderOpenId ? `${chatId}:sender:${senderOpenId}` : chatId;
+    case "group":
+    default:
+      return chatId;
+  }
+}
+
+export function parseFeishuTargetId(raw: unknown): string | undefined {
+  const target = normalizeText(raw);
+  if (!target) {
+    return undefined;
+  }
+  const withoutProvider = target.replace(/^(feishu|lark):/i, "").trim();
+  if (!withoutProvider) {
+    return undefined;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(withoutProvider);
+  for (const prefix of ["chat:", "group:", "channel:", "user:", "dm:", "open_id:"]) {
+    if (lowered.startsWith(prefix)) {
+      return normalizeText(withoutProvider.slice(prefix.length));
+    }
+  }
+  return withoutProvider;
+}
+
+export function parseFeishuDirectConversationId(raw: unknown): string | undefined {
+  const target = normalizeText(raw);
+  if (!target) {
+    return undefined;
+  }
+  const withoutProvider = target.replace(/^(feishu|lark):/i, "").trim();
+  if (!withoutProvider) {
+    return undefined;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(withoutProvider);
+  for (const prefix of ["user:", "dm:", "open_id:"]) {
+    if (lowered.startsWith(prefix)) {
+      return normalizeText(withoutProvider.slice(prefix.length));
+    }
+  }
+  const id = parseFeishuTargetId(target);
+  if (!id) {
+    return undefined;
+  }
+  if (id.startsWith("ou_") || id.startsWith("on_")) {
+    return id;
+  }
+  return undefined;
+}
+
+export function parseFeishuConversationId(params: {
+  conversationId: string;
+  parentConversationId?: string;
+}): {
+  canonicalConversationId: string;
+  chatId: string;
+  topicId?: string;
+  senderOpenId?: string;
+  scope: FeishuGroupSessionScope;
+} | null {
+  const conversationId = normalizeText(params.conversationId);
+  const parentConversationId = normalizeText(params.parentConversationId);
+  if (!conversationId) {
+    return null;
+  }
+
+  const topicSenderMatch = conversationId.match(/^(.+):topic:([^:]+):sender:([^:]+)$/i);
+  if (topicSenderMatch) {
+    const [, chatId, topicId, senderOpenId] = topicSenderMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_topic_sender",
+        topicId,
+        senderOpenId,
+      }),
+      chatId,
+      topicId,
+      senderOpenId,
+      scope: "group_topic_sender",
+    };
+  }
+
+  const topicMatch = conversationId.match(/^(.+):topic:([^:]+)$/i);
+  if (topicMatch) {
+    const [, chatId, topicId] = topicMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_topic",
+        topicId,
+      }),
+      chatId,
+      topicId,
+      scope: "group_topic",
+    };
+  }
+
+  const senderMatch = conversationId.match(/^(.+):sender:([^:]+)$/i);
+  if (senderMatch) {
+    const [, chatId, senderOpenId] = senderMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_sender",
+        senderOpenId,
+      }),
+      chatId,
+      senderOpenId,
+      scope: "group_sender",
+    };
+  }
+
+  if (parentConversationId) {
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId: parentConversationId,
+        scope: "group_topic",
+        topicId: conversationId,
+      }),
+      chatId: parentConversationId,
+      topicId: conversationId,
+      scope: "group_topic",
+    };
+  }
+
+  return {
+    canonicalConversationId: conversationId,
+    chatId: conversationId,
+    scope: "group",
+  };
+}
+
+export function buildFeishuModelOverrideParentCandidates(
+  parentConversationId?: string | null,
+): string[] {
+  const rawId = normalizeText(parentConversationId);
+  if (!rawId) {
+    return [];
+  }
+  const topicSenderMatch = rawId.match(/^(.+):topic:([^:]+):sender:([^:]+)$/i);
+  if (topicSenderMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(topicSenderMatch[1]);
+    const topicId = normalizeLowercaseStringOrEmpty(topicSenderMatch[2]);
+    if (chatId && topicId) {
+      return [`${chatId}:topic:${topicId}`, chatId];
+    }
+    return [];
+  }
+  const topicMatch = rawId.match(/^(.+):topic:([^:]+)$/i);
+  if (topicMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(topicMatch[1]);
+    return chatId ? [chatId] : [];
+  }
+  const senderMatch = rawId.match(/^(.+):sender:([^:]+)$/i);
+  if (senderMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(senderMatch[1]);
+    return chatId ? [chatId] : [];
+  }
+  return [];
+}

package/src/dedup-runtime-api.ts

@@ -0,0 +1 @@
+export { createPersistentDedupe } from "autobot/plugin-sdk/persistent-dedupe";

package/src/dedup.ts

@@ -0,0 +1,141 @@
+import os from "node:os";
+import path from "node:path";
+import { createPersistentDedupe } from "./dedup-runtime-api.js";
+import {
+  releaseFeishuMessageProcessing,
+  tryBeginFeishuMessageProcessing,
+} from "./processing-claims.js";
+
+// Persistent TTL: 24 hours — survives restarts & WebSocket reconnects.
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const MEMORY_MAX_SIZE = 1_000;
+const FILE_MAX_ENTRIES = 10_000;
+
+function resolveStateDirFromEnv(env: NodeJS.ProcessEnv = process.env): string {
+  const stateOverride = env.AUTOBOT_STATE_DIR?.trim();
+  if (stateOverride) {
+    return stateOverride;
+  }
+  if (env.VITEST || env.NODE_ENV === "test") {
+    return path.join(os.tmpdir(), ["autobot-vitest", String(process.pid)].join("-"));
+  }
+  return path.join(os.homedir(), ".autobot");
+}
+
+function resolveNamespaceFilePath(namespace: string): string {
+  const safe = namespace.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(resolveStateDirFromEnv(), "feishu", "dedup", `${safe}.json`);
+}
+
+const persistentDedupe = createPersistentDedupe({
+  ttlMs: DEDUP_TTL_MS,
+  memoryMaxSize: MEMORY_MAX_SIZE,
+  fileMaxEntries: FILE_MAX_ENTRIES,
+  resolveFilePath: resolveNamespaceFilePath,
+});
+
+function normalizeMessageId(messageId: string | undefined | null): string | null {
+  const trimmed = messageId?.trim();
+  return trimmed ? trimmed : null;
+}
+
+export { releaseFeishuMessageProcessing, tryBeginFeishuMessageProcessing };
+
+export async function claimUnprocessedFeishuMessage(params: {
+  messageId: string | undefined | null;
+  namespace?: string;
+  log?: (...args: unknown[]) => void;
+}): Promise<"claimed" | "duplicate" | "inflight" | "invalid"> {
+  const { messageId, namespace = "global", log } = params;
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return "invalid";
+  }
+  if (await hasProcessedFeishuMessage(normalizedMessageId, namespace, log)) {
+    return "duplicate";
+  }
+  if (!tryBeginFeishuMessageProcessing(normalizedMessageId, namespace)) {
+    return "inflight";
+  }
+  return "claimed";
+}
+
+export async function finalizeFeishuMessageProcessing(params: {
+  messageId: string | undefined | null;
+  namespace?: string;
+  log?: (...args: unknown[]) => void;
+  claimHeld?: boolean;
+}): Promise<boolean> {
+  const { messageId, namespace = "global", log, claimHeld = false } = params;
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  if (!claimHeld && !tryBeginFeishuMessageProcessing(normalizedMessageId, namespace)) {
+    return false;
+  }
+  if (!(await tryRecordMessagePersistent(normalizedMessageId, namespace, log))) {
+    releaseFeishuMessageProcessing(normalizedMessageId, namespace);
+    return false;
+  }
+  return true;
+}
+
+export async function recordProcessedFeishuMessage(
+  messageId: string | undefined | null,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  return await tryRecordMessagePersistent(normalizedMessageId, namespace, log);
+}
+
+export async function hasProcessedFeishuMessage(
+  messageId: string | undefined | null,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  return hasRecordedMessagePersistent(normalizedMessageId, namespace, log);
+}
+
+export async function tryRecordMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  return persistentDedupe.checkAndRecord(messageId, {
+    namespace,
+    onDiskError: (error) => {
+      log?.(`feishu-dedup: disk error, falling back to memory: ${String(error)}`);
+    },
+  });
+}
+
+async function hasRecordedMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  return persistentDedupe.hasRecent(messageId, {
+    namespace,
+    onDiskError: (error) => {
+      log?.(`feishu-dedup: persistent peek failed: ${String(error)}`);
+    },
+  });
+}
+
+export async function warmupDedupFromDisk(
+  namespace: string,
+  log?: (...args: unknown[]) => void,
+): Promise<number> {
+  return persistentDedupe.warmup(namespace, (error) => {
+    log?.(`feishu-dedup: warmup disk error: ${String(error)}`);
+  });
+}