@actagent/feishu 2026.6.2

package/src/conversation-id.ts

@@ -0,0 +1,199 @@
+// Feishu plugin module implements conversation id behavior.
+import { normalizeLowercaseStringOrEmpty } from "actagent/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;
+    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-migrations.test.ts

@@ -0,0 +1,90 @@
+// Feishu tests cover dedup migrations plugin behavior.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { detectFeishuLegacyStateMigrations } from "./dedup-migrations.js";
+
+const tempDirs: string[] = [];
+
+async function makeStateDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "actagent-feishu-dedup-migration-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  vi.useRealTimers();
+  await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+describe("Feishu dedupe migration", () => {
+  it("plans recent legacy dedupe rows with remaining TTL", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(2_000);
+    const stateDir = await makeStateDir();
+    const sourcePath = path.join(stateDir, "feishu", "dedup", "account-a.json");
+    await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+    await fs.writeFile(
+      sourcePath,
+      JSON.stringify({
+        fresh: 1_000,
+        expired: 2_000 - 24 * 60 * 60 * 1000,
+        malformed: "nope",
+      }),
+    );
+
+    const plans = await Promise.resolve(
+      detectFeishuLegacyStateMigrations({
+        cfg: {},
+        env: {},
+        oauthDir: path.join(stateDir, "credentials"),
+        stateDir,
+      }),
+    );
+
+    if (!plans) {
+      throw new Error("expected migration plans");
+    }
+    expect(plans).toHaveLength(1);
+    const plan = plans[0];
+    expect(plan?.kind).toBe("plugin-state-import");
+    if (plan?.kind !== "plugin-state-import") {
+      throw new Error("expected plugin-state import plan");
+    }
+    expect(plan.pluginId).toBe("feishu");
+    expect(plan.namespace).toBe("dedup.account-a");
+    const entries = await plan.readEntries();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.key).toMatch(/^[0-9a-f]{32}$/u);
+    expect(entries[0]?.value).toEqual({
+      namespace: "account-a",
+      messageId: "fresh",
+      seenAt: 1_000,
+    });
+    expect(entries[0]?.ttlMs).toBe(24 * 60 * 60 * 1000 - 1_000);
+  });
+
+  it("skips expired-only legacy dedupe files", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(2_000);
+    const stateDir = await makeStateDir();
+    const sourcePath = path.join(stateDir, "feishu", "dedup", "account-a.json");
+    await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+    await fs.writeFile(
+      sourcePath,
+      JSON.stringify({
+        expired: 2_000 - 24 * 60 * 60 * 1000,
+      }),
+    );
+
+    expect(
+      detectFeishuLegacyStateMigrations({
+        cfg: {},
+        env: {},
+        oauthDir: path.join(stateDir, "credentials"),
+        stateDir,
+      }),
+    ).toStrictEqual([]);
+  });
+});

package/src/dedup-migrations.ts

@@ -0,0 +1,103 @@
+// Feishu plugin module implements dedup migrations behavior.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { BundledChannelLegacyStateMigrationDetector } from "actagent/plugin-sdk/channel-entry-contract";
+
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const STORE_MAX_ENTRIES = 10_000;
+
+type LegacyDedupeData = Record<string, number>;
+
+function safeNamespaceFromFileName(fileName: string): string | null {
+  if (!fileName.endsWith(".json")) {
+    return null;
+  }
+  const namespace = fileName.slice(0, -".json".length).trim();
+  return namespace ? namespace : null;
+}
+
+function readLegacyDedupeData(filePath: string): LegacyDedupeData {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const out: LegacyDedupeData = {};
+    for (const [messageId, seenAt] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof seenAt === "number" && Number.isFinite(seenAt) && seenAt > 0) {
+        out[messageId] = seenAt;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function dedupeStoreKey(namespace: string, messageId: string): string {
+  return createHash("sha256")
+    .update(`${namespace}\0${messageId}`, "utf8")
+    .digest("hex")
+    .slice(0, 32);
+}
+
+function remainingTtlMs(seenAt: number, now: number): number {
+  return Math.max(1, DEDUP_TTL_MS - (now - seenAt));
+}
+
+function buildMigrationEntries(namespace: string, sourcePath: string, now: number) {
+  return Object.entries(readLegacyDedupeData(sourcePath)).flatMap(([messageId, seenAt]) => {
+    if (now - seenAt >= DEDUP_TTL_MS) {
+      return [];
+    }
+    return [
+      {
+        key: dedupeStoreKey(namespace, messageId),
+        value: { namespace, messageId, seenAt },
+        ttlMs: remainingTtlMs(seenAt, now),
+      },
+    ];
+  });
+}
+
+export const detectFeishuLegacyStateMigrations: BundledChannelLegacyStateMigrationDetector = ({
+  stateDir,
+}) => {
+  const dedupDir = path.join(stateDir, "feishu", "dedup");
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dedupDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const now = Date.now();
+  return entries.flatMap((entry) => {
+    if (!entry.isFile()) {
+      return [];
+    }
+    const namespace = safeNamespaceFromFileName(entry.name);
+    if (!namespace) {
+      return [];
+    }
+    const sourcePath = path.join(dedupDir, entry.name);
+    const migrationEntries = buildMigrationEntries(namespace, sourcePath, now);
+    if (migrationEntries.length === 0) {
+      return [];
+    }
+    return [
+      {
+        kind: "plugin-state-import" as const,
+        label: `Feishu ${namespace} dedupe`,
+        sourcePath,
+        targetPath: `plugin state:dedup.${namespace}`,
+        pluginId: "feishu",
+        namespace: `dedup.${namespace}`,
+        maxEntries: STORE_MAX_ENTRIES,
+        scopeKey: "",
+        cleanupSource: "rename" as const,
+        readEntries: () => buildMigrationEntries(namespace, sourcePath, now),
+      },
+    ];
+  });
+};

package/src/dedup.test.ts

@@ -0,0 +1,95 @@
+// Feishu tests cover dedup plugin behavior.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { OpenKeyedStoreOptions } from "actagent/plugin-sdk/plugin-state-runtime";
+import {
+  createPluginStateSyncKeyedStoreForTests,
+  resetPluginStateStoreForTests,
+} from "actagent/plugin-sdk/plugin-state-test-runtime";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PluginRuntime } from "../runtime-api.js";
+import {
+  hasProcessedFeishuMessage,
+  testingHooks,
+  tryRecordMessagePersistent,
+  warmupDedupFromPluginState,
+} from "./dedup.js";
+import { setFeishuRuntime } from "./runtime.js";
+
+let tempDir: string | undefined;
+let previousStateDir: string | undefined;
+
+beforeEach(async () => {
+  previousStateDir = process.env.ACTAGENT_STATE_DIR;
+  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "actagent-feishu-dedup-"));
+  process.env.ACTAGENT_STATE_DIR = tempDir;
+  setFeishuRuntime({
+    state: {
+      openSyncKeyedStore: (options: OpenKeyedStoreOptions) =>
+        createPluginStateSyncKeyedStoreForTests("feishu", options),
+    },
+  } as unknown as PluginRuntime);
+  testingHooks.resetFeishuDedupForTests();
+});
+
+afterEach(async () => {
+  vi.useRealTimers();
+  testingHooks.resetFeishuDedupForTests();
+  resetPluginStateStoreForTests();
+  if (previousStateDir === undefined) {
+    delete process.env.ACTAGENT_STATE_DIR;
+  } else {
+    process.env.ACTAGENT_STATE_DIR = previousStateDir;
+  }
+  if (tempDir) {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+  tempDir = undefined;
+});
+
+describe("Feishu persistent dedupe", () => {
+  it("records message ids in plugin state", async () => {
+    await expect(tryRecordMessagePersistent("msg-1", "account-a")).resolves.toBe(true);
+    await expect(tryRecordMessagePersistent("msg-1", "account-a")).resolves.toBe(false);
+    await expect(hasProcessedFeishuMessage("msg-1", "account-a")).resolves.toBe(true);
+    await expect(hasProcessedFeishuMessage("msg-1", "account-b")).resolves.toBe(false);
+  });
+
+  it("warms memory from persisted plugin state", async () => {
+    await expect(tryRecordMessagePersistent("msg-2", "account-a")).resolves.toBe(true);
+    testingHooks.resetFeishuDedupMemoryForTests();
+
+    await expect(warmupDedupFromPluginState("account-a")).resolves.toBe(1);
+    await expect(tryRecordMessagePersistent("msg-2", "account-a")).resolves.toBe(false);
+  });
+
+  it("ignores expired persisted entries", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    await expect(tryRecordMessagePersistent("msg-3", "account-a")).resolves.toBe(true);
+    testingHooks.resetFeishuDedupMemoryForTests();
+
+    vi.setSystemTime(1_000 + 24 * 60 * 60 * 1000 + 1);
+    await expect(hasProcessedFeishuMessage("msg-3", "account-a")).resolves.toBe(false);
+  });
+
+  it("ignores legacy JSON dedupe files at runtime", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(2_000);
+    const legacyPath = path.join(tempDir as string, "feishu", "dedup", "account-a.json");
+    await fs.mkdir(path.dirname(legacyPath), { recursive: true });
+    await fs.writeFile(
+      legacyPath,
+      JSON.stringify({
+        "msg-legacy": 1_000,
+        "msg-expired": 2_000 - 24 * 60 * 60 * 1000 - 1,
+      }),
+      "utf8",
+    );
+
+    await expect(hasProcessedFeishuMessage("msg-legacy", "account-a")).resolves.toBe(false);
+    await expect(tryRecordMessagePersistent("msg-legacy", "account-a")).resolves.toBe(true);
+    await expect(hasProcessedFeishuMessage("msg-expired", "account-a")).resolves.toBe(false);
+  });
+});