@actagent/feishu 2026.6.2

package/src/dedup.ts

@@ -0,0 +1,304 @@
+// Feishu plugin module implements dedup behavior.
+import { createHash } from "node:crypto";
+import type { PluginStateSyncKeyedStore } from "actagent/plugin-sdk/plugin-state-runtime";
+import {
+  releaseFeishuMessageProcessing,
+  tryBeginFeishuMessageProcessing,
+} from "./processing-claims.js";
+import { getFeishuRuntime } from "./runtime.js";
+
+// Persistent TTL: 24 hours — survives restarts & WebSocket reconnects.
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const MEMORY_MAX_SIZE = 1_000;
+const STORE_MAX_ENTRIES = 10_000;
+type FeishuDedupStoreEntry = {
+  namespace: string;
+  messageId: string;
+  seenAt: number;
+};
+
+const memory = new Map<string, number>();
+const cachedDedupStores = new Map<string, PluginStateSyncKeyedStore<FeishuDedupStoreEntry>>();
+
+function normalizeMessageId(messageId: string | undefined | null): string | null {
+  const trimmed = messageId?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function normalizeNamespace(namespace?: string): string {
+  return namespace?.trim() || "global";
+}
+
+function pluginStateNamespace(namespace: string): string {
+  return `dedup.${namespace.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+}
+
+function openDedupStore(namespace: string): PluginStateSyncKeyedStore<FeishuDedupStoreEntry> {
+  const stateNamespace = pluginStateNamespace(namespace);
+  const cached = cachedDedupStores.get(stateNamespace);
+  if (cached) {
+    return cached;
+  }
+  const store = getFeishuRuntime().state.openSyncKeyedStore<FeishuDedupStoreEntry>({
+    namespace: stateNamespace,
+    maxEntries: STORE_MAX_ENTRIES,
+    defaultTtlMs: DEDUP_TTL_MS,
+  });
+  cachedDedupStores.set(stateNamespace, store);
+  return store;
+}
+
+function dedupeStoreKey(namespace: string, messageId: string): string {
+  return createHash("sha256")
+    .update(`${namespace}\0${messageId}`, "utf8")
+    .digest("hex")
+    .slice(0, 32);
+}
+
+function memoryKey(namespace: string, messageId: string): string {
+  return `${namespace}\0${messageId}`;
+}
+
+function isRecent(seenAt: number | undefined, now = Date.now()): boolean {
+  return typeof seenAt === "number" && Number.isFinite(seenAt) && now - seenAt < DEDUP_TTL_MS;
+}
+
+function pruneMemory(now = Date.now()): void {
+  for (const [key, seenAt] of memory) {
+    if (!isRecent(seenAt, now)) {
+      memory.delete(key);
+    }
+  }
+  if (memory.size <= MEMORY_MAX_SIZE) {
+    return;
+  }
+  const toRemove = Array.from(memory.entries())
+    .toSorted(([, left], [, right]) => left - right)
+    .slice(0, memory.size - MEMORY_MAX_SIZE);
+  for (const [key] of toRemove) {
+    memory.delete(key);
+  }
+}
+
+function remember(namespace: string, messageId: string, seenAt = Date.now()): void {
+  memory.set(memoryKey(namespace, messageId), seenAt);
+  pruneMemory(seenAt);
+}
+
+function hasMemory(namespace: string, messageId: string, now = Date.now()): boolean {
+  const key = memoryKey(namespace, messageId);
+  const seenAt = memory.get(key);
+  if (isRecent(seenAt, now)) {
+    return true;
+  }
+  memory.delete(key);
+  return false;
+}
+
+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 forgetProcessedFeishuMessage(
+  messageId: string | undefined | null,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedNamespace = normalizeNamespace(namespace);
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  memory.delete(memoryKey(normalizedNamespace, normalizedMessageId));
+  const key = dedupeStoreKey(normalizedNamespace, normalizedMessageId);
+  try {
+    return openDedupStore(normalizedNamespace).delete(key);
+  } catch (error) {
+    log?.(`feishu-dedup: persistent delete failed: ${String(error)}`);
+    return false;
+  }
+}
+
+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> {
+  const normalizedNamespace = normalizeNamespace(namespace);
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return true;
+  }
+  const now = Date.now();
+  if (hasMemory(normalizedNamespace, normalizedMessageId, now)) {
+    return false;
+  }
+  const key = dedupeStoreKey(normalizedNamespace, normalizedMessageId);
+  try {
+    const store = openDedupStore(normalizedNamespace);
+    const existing = store.lookup(key);
+    const existingSeenAt = existing?.seenAt;
+    if (isRecent(existingSeenAt, now)) {
+      remember(normalizedNamespace, normalizedMessageId, existingSeenAt);
+      return false;
+    }
+    const recorded = store.registerIfAbsent(
+      key,
+      {
+        namespace: normalizedNamespace,
+        messageId: normalizedMessageId,
+        seenAt: now,
+      },
+      { ttlMs: DEDUP_TTL_MS },
+    );
+    if (!recorded) {
+      const current = store.lookup(key);
+      const currentSeenAt = current?.seenAt;
+      if (isRecent(currentSeenAt, now)) {
+        remember(normalizedNamespace, normalizedMessageId, currentSeenAt);
+        return false;
+      }
+      store.register(
+        key,
+        {
+          namespace: normalizedNamespace,
+          messageId: normalizedMessageId,
+          seenAt: now,
+        },
+        { ttlMs: DEDUP_TTL_MS },
+      );
+    }
+    remember(normalizedNamespace, normalizedMessageId, now);
+    return true;
+  } catch (error) {
+    log?.(`feishu-dedup: persistent state error, falling back to memory: ${String(error)}`);
+    remember(normalizedNamespace, normalizedMessageId, now);
+    return true;
+  }
+}
+
+async function hasRecordedMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedNamespace = normalizeNamespace(namespace);
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  const now = Date.now();
+  if (hasMemory(normalizedNamespace, normalizedMessageId, now)) {
+    return true;
+  }
+  try {
+    const store = openDedupStore(normalizedNamespace);
+    const existing = store.lookup(dedupeStoreKey(normalizedNamespace, normalizedMessageId));
+    const existingSeenAt = existing?.seenAt;
+    if (!isRecent(existingSeenAt, now)) {
+      return false;
+    }
+    remember(normalizedNamespace, normalizedMessageId, existingSeenAt);
+    return true;
+  } catch (error) {
+    log?.(`feishu-dedup: persistent peek failed: ${String(error)}`);
+    return hasMemory(normalizedNamespace, normalizedMessageId, now);
+  }
+}
+
+export async function warmupDedupFromPluginState(
+  namespace: string,
+  log?: (...args: unknown[]) => void,
+): Promise<number> {
+  const normalizedNamespace = normalizeNamespace(namespace);
+  try {
+    let loaded = 0;
+    const now = Date.now();
+    for (const entry of openDedupStore(normalizedNamespace).entries()) {
+      if (entry.value.namespace !== normalizedNamespace || !isRecent(entry.value.seenAt, now)) {
+        continue;
+      }
+      remember(normalizedNamespace, entry.value.messageId, entry.value.seenAt);
+      loaded++;
+    }
+    return loaded;
+  } catch (error) {
+    log?.(`feishu-dedup: warmup persistent state error: ${String(error)}`);
+    return 0;
+  }
+}
+
+export const testingHooks = {
+  resetFeishuDedupForTests() {
+    memory.clear();
+    for (const store of cachedDedupStores.values()) {
+      store.clear();
+    }
+    cachedDedupStores.clear();
+  },
+  resetFeishuDedupMemoryForTests() {
+    memory.clear();
+  },
+};

package/src/dedupe-key.ts

@@ -0,0 +1,68 @@
+// Feishu plugin module implements dedupe key behavior.
+import { asNullableRecord as readRecord } from "actagent/plugin-sdk/string-coerce-runtime";
+import type { FeishuMessageEvent } from "./event-types.js";
+import { normalizeFeishuExternalKey } from "./external-keys.js";
+import { parsePostContent } from "./post.js";
+
+type FeishuMessageDedupeInput = Pick<FeishuMessageEvent, "message">;
+
+function readExternalKey(value: unknown): string | undefined {
+  return normalizeFeishuExternalKey(typeof value === "string" ? value : "");
+}
+
+function parseContentRecord(content: string): Record<string, unknown> | null {
+  try {
+    return readRecord(JSON.parse(content));
+  } catch {
+    return null;
+  }
+}
+
+function buildMediaDedupeKey(messageId: string, mediaParts: string[]): string {
+  return JSON.stringify([messageId, ...mediaParts]);
+}
+
+function resolvePostMediaParts(content: string): string[] {
+  const parsed = parsePostContent(content);
+  return [
+    ...parsed.imageKeys.map((imageKey) => `image_key:${imageKey}`),
+    ...parsed.mediaKeys.map((media) => `file_key:${media.fileKey}`),
+  ];
+}
+
+function resolveMessageMediaParts(messageType: string, content: string): string[] {
+  if (messageType === "post") {
+    return resolvePostMediaParts(content);
+  }
+
+  const parsed = parseContentRecord(content);
+  if (!parsed) {
+    return [];
+  }
+
+  const imageKey = readExternalKey(parsed.image_key);
+  const fileKey = readExternalKey(parsed.file_key);
+  switch (messageType) {
+    case "image":
+      return imageKey ? [`image_key:${imageKey}`] : [];
+    case "file":
+    case "audio":
+    case "sticker":
+      return fileKey ? [`file_key:${fileKey}`] : [];
+    case "video":
+    case "media":
+      return fileKey ? [`file_key:${fileKey}`] : imageKey ? [`image_key:${imageKey}`] : [];
+    default:
+      return fileKey ? [`file_key:${fileKey}`] : imageKey ? [`image_key:${imageKey}`] : [];
+  }
+}
+
+export function resolveFeishuMessageDedupeKey(event: FeishuMessageDedupeInput): string | undefined {
+  const messageId = event.message.message_id?.trim();
+  if (!messageId) {
+    return undefined;
+  }
+  const messageType = event.message.message_type.trim();
+  const mediaParts = resolveMessageMediaParts(messageType, event.message.content);
+  return mediaParts.length > 0 ? buildMediaDedupeKey(messageId, mediaParts) : messageId;
+}

package/src/directory.static.ts

@@ -0,0 +1,62 @@
+// Feishu plugin module implements directory.static behavior.
+import {
+  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
+  listDirectoryUserEntriesFromAllowFromAndMapKeys,
+} from "actagent/plugin-sdk/directory-runtime";
+import type { ACTAgentBotConfig } from "../runtime-api.js";
+import { resolveFeishuAccount } from "./accounts.js";
+import { normalizeFeishuTarget } from "./targets.js";
+
+export type FeishuDirectoryPeer = {
+  kind: "user";
+  id: string;
+  name?: string;
+};
+
+export type FeishuDirectoryGroup = {
+  kind: "group";
+  id: string;
+  name?: string;
+};
+
+function toFeishuDirectoryPeers(ids: string[]): FeishuDirectoryPeer[] {
+  return ids.map((id) => ({ kind: "user", id }));
+}
+
+function toFeishuDirectoryGroups(ids: string[]): FeishuDirectoryGroup[] {
+  return ids.map((id) => ({ kind: "group", id }));
+}
+
+export async function listFeishuDirectoryPeers(params: {
+  cfg: ACTAgentBotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): Promise<FeishuDirectoryPeer[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  const entries = listDirectoryUserEntriesFromAllowFromAndMapKeys({
+    allowFrom: account.config.allowFrom,
+    map: account.config.dms,
+    query: params.query,
+    limit: params.limit,
+    normalizeAllowFromId: (entry) => normalizeFeishuTarget(entry) ?? entry,
+    normalizeMapKeyId: (entry) => normalizeFeishuTarget(entry) ?? entry,
+  });
+  return toFeishuDirectoryPeers(entries.map((entry) => entry.id));
+}
+
+export async function listFeishuDirectoryGroups(params: {
+  cfg: ACTAgentBotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): Promise<FeishuDirectoryGroup[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  const entries = listDirectoryGroupEntriesFromMapKeysAndAllowFrom({
+    groups: account.config.groups,
+    allowFrom: account.config.groupAllowFrom,
+    query: params.query,
+    limit: params.limit,
+  });
+  return toFeishuDirectoryGroups(entries.map((entry) => entry.id));
+}

package/src/directory.test.ts

@@ -0,0 +1,142 @@
+// Feishu tests cover directory plugin behavior.
+import { importFreshModule } from "actagent/plugin-sdk/test-fixtures";
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ACTAgentBotConfig } from "../runtime-api.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+const { listFeishuDirectoryGroupsLive, listFeishuDirectoryPeersLive } = await importFreshModule<
+  typeof import("./directory.js")
+>(import.meta.url, "./directory.js?directory-test");
+const { listFeishuDirectoryGroups, listFeishuDirectoryPeers } = await importFreshModule<
+  typeof import("./directory.static.js")
+>(import.meta.url, "./directory.static.js?directory-test");
+
+function makeStaticCfg(): ACTAgentBotConfig {
+  return {
+    channels: {
+      feishu: {
+        allowFrom: ["user:alice", "user:bob"],
+        dms: {
+          "user:carla": {},
+        },
+        groups: {
+          "chat-1": {},
+        },
+        groupAllowFrom: ["chat-2"],
+      },
+    },
+  } as ACTAgentBotConfig;
+}
+
+function makeConfiguredCfg(): ACTAgentBotConfig {
+  return {
+    channels: {
+      feishu: {
+        ...makeStaticCfg().channels?.feishu,
+        appId: "cli_test_app_id",
+        appSecret: "cli_test_app_secret",
+      },
+    },
+  } as ACTAgentBotConfig;
+}
+
+describe("feishu directory (config-backed)", () => {
+  afterAll(() => {
+    vi.doUnmock("./client.js");
+    vi.resetModules();
+  });
+
+  beforeEach(() => {
+    createFeishuClientMock.mockReset();
+  });
+
+  it("merges allowFrom + dms into peer entries", async () => {
+    const peers = await listFeishuDirectoryPeers({ cfg: makeStaticCfg(), query: "a" });
+    expect(peers).toEqual([
+      { kind: "user", id: "alice" },
+      { kind: "user", id: "carla" },
+    ]);
+  });
+
+  it("normalizes spaced provider-prefixed peer entries", async () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          allowFrom: [" feishu:user:ou_alice "],
+          dms: {
+            " lark:dm:ou_carla ": {},
+          },
+          groups: {},
+          groupAllowFrom: [],
+        },
+      },
+    } as ACTAgentBotConfig;
+
+    const peers = await listFeishuDirectoryPeers({ cfg });
+    expect(peers).toEqual([
+      { kind: "user", id: "ou_alice" },
+      { kind: "user", id: "ou_carla" },
+    ]);
+  });
+
+  it("merges groups map + groupAllowFrom into group entries", async () => {
+    const groups = await listFeishuDirectoryGroups({ cfg: makeStaticCfg() });
+    expect(groups).toEqual([
+      { kind: "group", id: "chat-1" },
+      { kind: "group", id: "chat-2" },
+    ]);
+  });
+
+  it("falls back to static peers on live lookup failure by default", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      contact: {
+        user: {
+          list: vi.fn(async () => {
+            throw new Error("token expired");
+          }),
+        },
+      },
+    });
+
+    const peers = await listFeishuDirectoryPeersLive({ cfg: makeConfiguredCfg(), query: "a" });
+    expect(peers).toEqual([
+      { kind: "user", id: "alice" },
+      { kind: "user", id: "carla" },
+    ]);
+  });
+
+  it("surfaces live peer lookup failures when fallback is disabled", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      contact: {
+        user: {
+          list: vi.fn(async () => {
+            throw new Error("token expired");
+          }),
+        },
+      },
+    });
+
+    await expect(
+      listFeishuDirectoryPeersLive({ cfg: makeConfiguredCfg(), fallbackToStatic: false }),
+    ).rejects.toThrow("token expired");
+  });
+
+  it("surfaces live group lookup failures when fallback is disabled", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      im: {
+        chat: {
+          list: vi.fn(async () => ({ code: 999, msg: "forbidden" })),
+        },
+      },
+    });
+
+    await expect(
+      listFeishuDirectoryGroupsLive({ cfg: makeConfiguredCfg(), fallbackToStatic: false }),
+    ).rejects.toThrow("forbidden");
+  });
+});

package/src/directory.ts

@@ -0,0 +1,125 @@
+// Feishu plugin module implements directory behavior.
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+import type { ACTAgentBotConfig } from "../runtime-api.js";
+import { resolveFeishuAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import {
+  listFeishuDirectoryGroups,
+  listFeishuDirectoryPeers,
+  type FeishuDirectoryGroup,
+  type FeishuDirectoryPeer,
+} from "./directory.static.js";
+
+export async function listFeishuDirectoryPeersLive(params: {
+  cfg: ACTAgentBotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+  fallbackToStatic?: boolean;
+}): Promise<FeishuDirectoryPeer[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    return listFeishuDirectoryPeers(params);
+  }
+
+  try {
+    const client = createFeishuClient(account);
+    const peers: FeishuDirectoryPeer[] = [];
+    const limit = params.limit ?? 50;
+
+    const response = await client.contact.user.list({
+      params: {
+        page_size: Math.min(limit, 50),
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(response.msg || `code ${response.code}`);
+    }
+
+    const q = normalizeLowercaseStringOrEmpty(params.query);
+    for (const user of response.data?.items ?? []) {
+      if (user.open_id) {
+        const name = user.name || "";
+        if (
+          !q ||
+          normalizeLowercaseStringOrEmpty(user.open_id).includes(q) ||
+          normalizeLowercaseStringOrEmpty(name).includes(q)
+        ) {
+          peers.push({
+            kind: "user",
+            id: user.open_id,
+            name: name || undefined,
+          });
+        }
+      }
+      if (peers.length >= limit) {
+        break;
+      }
+    }
+
+    return peers;
+  } catch (err) {
+    if (params.fallbackToStatic === false) {
+      throw err instanceof Error ? err : new Error("Feishu live peer lookup failed");
+    }
+    return listFeishuDirectoryPeers(params);
+  }
+}
+
+export async function listFeishuDirectoryGroupsLive(params: {
+  cfg: ACTAgentBotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+  fallbackToStatic?: boolean;
+}): Promise<FeishuDirectoryGroup[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    return listFeishuDirectoryGroups(params);
+  }
+
+  try {
+    const client = createFeishuClient(account);
+    const groups: FeishuDirectoryGroup[] = [];
+    const limit = params.limit ?? 50;
+
+    const response = await client.im.chat.list({
+      params: {
+        page_size: Math.min(limit, 100),
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(response.msg || `code ${response.code}`);
+    }
+
+    const q = normalizeLowercaseStringOrEmpty(params.query);
+    for (const chat of response.data?.items ?? []) {
+      if (chat.chat_id) {
+        const name = chat.name || "";
+        if (
+          !q ||
+          normalizeLowercaseStringOrEmpty(chat.chat_id).includes(q) ||
+          normalizeLowercaseStringOrEmpty(name).includes(q)
+        ) {
+          groups.push({
+            kind: "group",
+            id: chat.chat_id,
+            name: name || undefined,
+          });
+        }
+      }
+      if (groups.length >= limit) {
+        break;
+      }
+    }
+
+    return groups;
+  } catch (err) {
+    if (params.fallbackToStatic === false) {
+      throw err instanceof Error ? err : new Error("Feishu live group lookup failed");
+    }
+    return listFeishuDirectoryGroups(params);
+  }
+}