@controlflow-ai/daemon 0.1.0

package/src/lark/server-integration.ts

@@ -0,0 +1,445 @@
+import { MessageStore } from '../db.js';
+import { boundAgents, loadLarkCredentials, type LarkCredential } from './credentials.js';
+import { extractMentionOpenIds, ingestLarkMessage, type LarkMessageEnvelope } from './event-router.js';
+import type { ReceivePolicy } from './dispatcher.js';
+import { addMessageReaction, createLarkApiClient, getChatInfo, getChatMembers, startLarkDaemon, type LarkDaemonHandle } from './ws-daemon.js';
+
+export interface LarkServerIntegrationOptions {
+  /** Shared MessageStore for DB operations (caller owns lifecycle). */
+  store: MessageStore;
+  policy?: ReceivePolicy;
+  botOpenIdByApp?: Map<string, string>;
+  logger?: Partial<Pick<Console, 'log' | 'warn' | 'error'>>;
+  configPath?: string;
+  startDaemon?: typeof startLarkDaemon;
+}
+
+export type LarkReloadResult =
+  | { ok: true; bots: string[]; started: string[]; stopped: string[]; restarted: string[] }
+  | { ok: false; bots: string[]; error: string };
+
+export interface LarkServerIntegrationResult {
+  handles: LarkDaemonHandle[];
+  reload(): LarkReloadResult;
+  stop(): void;
+}
+
+/**
+ * Load all Lark bots from credentials file.
+ */
+export function loadAllLarkBots(configPath?: string): LarkCredential[] {
+  const store = loadLarkCredentials(configPath);
+  return store.bots;
+}
+
+function textContent(envelope: LarkMessageEnvelope): string {
+  const raw = envelope.message?.content;
+  if (!raw) return '';
+  try {
+    const parsed = JSON.parse(raw) as { text?: unknown };
+    return typeof parsed.text === 'string' ? parsed.text : raw;
+  } catch {
+    return raw;
+  }
+}
+
+function mentionsBotLabel(envelope: LarkMessageEnvelope, bot: LarkCredential): boolean {
+  if (!bot.label) return false;
+  const expected = bot.label.trim().toLowerCase();
+  if (!expected) return false;
+  if (textContent(envelope).toLowerCase().includes(`@${expected}`)) return true;
+  return (envelope.message?.mentions ?? []).some((mention) => mention.name?.trim().toLowerCase() === expected);
+}
+
+
+function configuredOwnerUnionId(): string | null {
+  return process.env.PAL_OWNER_LARK_UNION_ID?.trim() || process.env.PAL_LARK_OWNER_UNION_ID?.trim() || null;
+}
+
+function senderUnionId(envelope: LarkMessageEnvelope): string | null {
+  return envelope.sender?.sender_id?.union_id?.trim() || null;
+}
+
+function senderOpenId(envelope: LarkMessageEnvelope): string | null {
+  return envelope.sender?.sender_id?.open_id?.trim() || null;
+}
+
+function deliveryReactionEmojiType(): string {
+  return process.env.PAL_LARK_ACTION_REACTION_EMOJI?.trim() || 'Typing';
+}
+
+function apiErrorMessage(err: unknown): string {
+  if (err instanceof Error) {
+    const responseData = (err as Error & { response?: { data?: unknown } }).response?.data;
+    if (responseData && typeof responseData === 'object') {
+      const data = responseData as { code?: unknown; msg?: unknown; message?: unknown };
+      const code = typeof data.code === 'number' || typeof data.code === 'string' ? `code=${data.code} ` : '';
+      const msg = typeof data.msg === 'string' ? data.msg : typeof data.message === 'string' ? data.message : err.message;
+      return `${code}${msg}`;
+    }
+    return err.message;
+  }
+  return String(err);
+}
+
+async function syncLarkRoomMetadata(input: {
+  bot: LarkCredential;
+  chatId: string;
+  roomId: string;
+  store: MessageStore;
+  botOpenId?: string | null;
+  agent?: string | null;
+  log: Pick<Console, 'log' | 'warn'>;
+}): Promise<void> {
+  const client = createLarkApiClient(input.bot.appId, input.bot.appSecret);
+  try {
+    const info = await getChatInfo({ client, chatId: input.chatId });
+    const name = info.name?.trim();
+    if (name) input.store.updateRoomDisplayName(input.roomId, name);
+  } catch (err) {
+    input.log.warn(`[lark/${input.bot.appId}] chat name sync failed chat=${input.chatId}: ${apiErrorMessage(err)}`);
+  }
+  if (input.botOpenId) {
+    const account = input.store.getChannelAccountByAppId(input.bot.appId);
+    const participantId = account?.provider_account_id
+      ? input.store.getOrCreateProviderIdentity({
+          provider: 'lark',
+          providerAccountId: account.provider_account_id,
+          externalType: 'bot',
+          externalId: input.botOpenId,
+          displayName: input.bot.label ?? input.agent ?? input.bot.appId,
+        }).identity.stable_handle
+      : input.botOpenId;
+    input.store.upsertRoomParticipant({
+      roomId: input.roomId,
+      participantId,
+      kind: 'bot',
+      displayName: input.bot.label ?? input.agent ?? input.bot.appId,
+      source: 'known_bot',
+    });
+  }
+  try {
+    const result = await getChatMembers({ client, chatId: input.chatId });
+    const account = input.store.getChannelAccountByAppId(input.bot.appId);
+    for (const member of result.members) {
+      const participantId = account?.provider_account_id
+        ? input.store.getOrCreateProviderIdentity({
+            provider: 'lark',
+            providerAccountId: account.provider_account_id,
+            externalType: 'user',
+            externalId: member.memberId,
+            displayName: member.name,
+          }).identity.stable_handle
+        : member.memberId;
+      input.store.upsertRoomParticipant({
+        roomId: input.roomId,
+        participantId,
+        kind: 'user',
+        displayName: member.name,
+        source: 'lark_member_api',
+      });
+    }
+    input.log.log(`[lark/${input.bot.appId}] synced chat metadata chat=${input.chatId} members=${result.members.length}`);
+  } catch (err) {
+    input.log.warn(`[lark/${input.bot.appId}] chat member sync failed chat=${input.chatId}: ${apiErrorMessage(err)}`);
+  }
+}
+
+async function syncExistingLarkGroupRooms(input: {
+  bots: LarkCredential[];
+  store: MessageStore;
+  botOpenIdByApp: Map<string, string>;
+  log: Pick<Console, 'log' | 'warn'>;
+}): Promise<void> {
+  const botsByApp = new Map(input.bots.map((bot) => [bot.appId, bot]));
+  const seen = new Set<string>();
+  for (const mapping of input.store.listLarkGroupRoomMappings()) {
+    const key = `${mapping.app_id}:${mapping.external_chat_id}:${mapping.room_id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const bot = botsByApp.get(mapping.app_id);
+    if (!bot) continue;
+    await syncLarkRoomMetadata({
+      bot,
+      chatId: mapping.external_chat_id,
+      roomId: mapping.room_id,
+      store: input.store,
+      botOpenId: input.botOpenIdByApp.get(bot.appId) ?? bot.botOpenId ?? mapping.bot_open_id,
+      agent: mapping.agent,
+      log: input.log,
+    });
+  }
+}
+
+async function resolveSenderUnionId(input: {
+  bot: LarkCredential;
+  envelope: LarkMessageEnvelope;
+  store: MessageStore;
+}): Promise<{ status: 'resolved'; unionId: string } | { status: 'missing_open_id' } | { status: 'pending'; reason: string }> {
+  const eventUnionId = senderUnionId(input.envelope);
+  if (eventUnionId) return { status: 'resolved', unionId: eventUnionId };
+
+  const openId = senderOpenId(input.envelope);
+  if (!openId) return { status: 'missing_open_id' };
+
+  const cached = input.store.getCachedProviderUnionId({ provider: 'lark', appId: input.bot.appId, openId });
+  if (cached) return { status: 'resolved', unionId: cached };
+
+  try {
+    const client = createLarkApiClient(input.bot.appId, input.bot.appSecret);
+    const response = await client.contact.user.batch({
+      params: { user_ids: [openId], user_id_type: 'open_id' },
+    });
+    const user = response.data?.items?.[0];
+    const unionId = user?.union_id?.trim();
+    if (!unionId) return { status: 'pending', reason: 'union_id_not_returned' };
+    input.store.cacheProviderUnionId({ provider: 'lark', appId: input.bot.appId, openId, unionId });
+    return { status: 'resolved', unionId };
+  } catch (err) {
+    return { status: 'pending', reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Start Lark WS connections on the Server.
+ * When a message arrives, it is ingested into the DB and a delivery is created
+ * for the bound agent.
+ *
+ * This replaces the Daemon-side lark integration. The Server is now the
+ * single entry point for all Lark messages.
+ */
+export function startLarkOnServer(options: LarkServerIntegrationOptions): LarkServerIntegrationResult {
+  const log = {
+    log: options.logger?.log ?? console.log,
+    warn: options.logger?.warn ?? console.warn,
+    error: options.logger?.error ?? console.error,
+  };
+  const policy = options.policy ?? 'every';
+  const msgStore = options.store;
+  const botOpenIdByApp = options.botOpenIdByApp ?? new Map<string, string>();
+  const startDaemon = options.startDaemon ?? startLarkDaemon;
+  const active = new Map<string, { bot: LarkCredential; handle: LarkDaemonHandle; fingerprint: string }>();
+
+  const activeBots = (): LarkCredential[] => Array.from(active.values()).map((entry) => entry.bot);
+  const activeHandles = (): LarkDaemonHandle[] => Array.from(active.values()).map((entry) => entry.handle);
+  const activeAppIds = (): string[] => activeHandles().map((handle) => handle.appId);
+  const credentialFingerprint = (bot: LarkCredential): string => JSON.stringify({
+    appId: bot.appId,
+    appSecret: bot.appSecret,
+    label: bot.label ?? null,
+    agent: bot.agent ?? null,
+    botOpenId: bot.botOpenId ?? null,
+  });
+
+  const loadBotsForReload = (): LarkCredential[] => {
+    const bots = loadAllLarkBots(options.configPath);
+    const seen = new Set<string>();
+    for (const bot of bots) {
+      if (seen.has(bot.appId)) throw new Error(`duplicate Lark appId in config: ${bot.appId}`);
+      seen.add(bot.appId);
+    }
+    return bots;
+  };
+
+  const afterSuccessfulScan = (bots: LarkCredential[]): void => {
+    const backfilledDmNames = msgStore.backfillLarkDmDisplayNames();
+    if (backfilledDmNames > 0) {
+      log.log(`[lark] backfilled ${backfilledDmNames} DM display name(s)`);
+    }
+    void syncExistingLarkGroupRooms({ bots, store: msgStore, botOpenIdByApp, log }).catch((err) => {
+      log.warn(`[lark] startup chat metadata sync failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  };
+
+  const startBot = (bot: LarkCredential): LarkDaemonHandle => startDaemon({
+    appId: bot.appId,
+    appSecret: bot.appSecret,
+    db: msgStore.db,
+    logger: { info: log.log, warn: log.warn, error: log.error },
+    onEvent: async ({ envelope, data, storeResult }) => {
+      log.log(`[lark/${bot.appId}] ${envelope} stored id=${storeResult.id} event_id=${storeResult.event_id} parse_ok=${storeResult.parse_ok}`);
+      if (envelope === 'im.message.receive_v1') {
+        try {
+          const larkEnvelope = data as LarkMessageEnvelope;
+          const ownerUnionId = configuredOwnerUnionId();
+          if (ownerUnionId) {
+            const identity = await resolveSenderUnionId({ bot, envelope: larkEnvelope, store: msgStore });
+            if (identity.status === 'pending') {
+              msgStore.recordPendingInboundEvent({ rawEventId: storeResult.event_id, provider: 'lark', reason: 'missing_union_id', error: identity.reason });
+              log.warn(`[lark/${bot.appId}] sender union_id lookup pending: ${identity.reason}`);
+              return;
+            }
+            if (identity.status !== 'resolved' || identity.unionId !== ownerUnionId) {
+              log.log(`[lark/${bot.appId}] business ingest skipped sender_union=${identity.status === 'resolved' ? identity.unionId : '-'} owner_configured=true`);
+              return;
+            }
+          }
+          const agents = boundAgents(bot);
+          const mentionOpenIds = extractMentionOpenIds(larkEnvelope);
+          const inferredBotOpenId = agents.length === 1 && mentionOpenIds.length === 1 ? mentionOpenIds[0] : null;
+          const botOpenId = botOpenIdByApp.get(bot.appId) ?? bot.botOpenId ?? inferredBotOpenId;
+          const recipientByMentionOpenId = new Map<string, string>();
+          if (botOpenId && agents.length === 1) recipientByMentionOpenId.set(botOpenId, agents[0]!);
+          const labelMentionedThisBot = mentionsBotLabel(larkEnvelope, bot);
+          const labelMentionedAnyKnownBot = activeBots().some((candidate) => mentionsBotLabel(larkEnvelope, candidate));
+          if (labelMentionedAnyKnownBot && !labelMentionedThisBot) {
+            log.log(`[lark/${bot.appId}] label mention targets another bot, skipping ingest`);
+            return;
+          }
+          const recipientOverride = larkEnvelope.message?.chat_type === 'p2p' && agents.length === 1
+            ? agents[0]!
+            : labelMentionedThisBot && agents.length === 1 ? agents[0]! : undefined;
+
+          const result = ingestLarkMessage({
+            appId: bot.appId,
+            envelope: larkEnvelope,
+            store: msgStore,
+            recipientByMentionOpenId,
+            recipientOverride,
+          });
+          if (result.status === 'ok' && result.message) {
+            const tag = result.deduped ? 'dup' : result.threadOrphan ? 'orphan' : 'new';
+            log.log(
+              `[lark/${bot.appId}] ingest ${tag} lock_msg=${result.message.id} chat=${result.message.chat_name} parent=${result.message.parent_id ?? '-'}`,
+            );
+            const larkMessage = (data as LarkMessageEnvelope).message;
+            if (larkMessage?.chat_id) {
+              try {
+                const account = msgStore.registerChannelAccount({
+                  name: bot.label ?? bot.appId,
+                  appId: bot.appId,
+                  botOpenId,
+                  agent: agents.length === 1 ? agents[0]! : null,
+                });
+                msgStore.resolveChannelConversation({
+                  accountId: account.id,
+                  chatName: result.message.chat_name,
+                  conversationKey: `${result.message.chat_name}:app:${bot.appId}`,
+                  externalChatId: larkMessage.chat_id,
+                  externalRootId: larkMessage.root_id ?? null,
+                  externalThreadId: larkMessage.thread_id ?? null,
+                  scope: larkMessage.root_id || larkMessage.thread_id ? 'thread' : larkMessage.chat_type === 'p2p' ? 'p2p' : 'chat',
+                  chatType: larkMessage.chat_type === 'p2p' ? 'p2p' : 'group',
+                  auditOnly: false,
+                });
+                await syncLarkRoomMetadata({
+                  bot,
+                  chatId: larkMessage.chat_id,
+                  roomId: result.message.chat_id,
+                  store: msgStore,
+                  botOpenId,
+                  agent: agents.length === 1 ? agents[0]! : null,
+                  log,
+                });
+              } catch (err) {
+                log.warn(`[lark/${bot.appId}] channel mapping failed: ${err instanceof Error ? err.message : String(err)}`);
+              }
+            }
+            if (tag === 'new' || result.deduped) {
+              const deliveries = msgStore.resolveDeliveriesForMessage(result.message.id);
+              if (deliveries.length === 0) {
+                log.log(`[lark/${bot.appId}] resolver created no deliveries message=${result.message.id}`);
+              } else {
+                for (const delivery of deliveries) {
+                  log.log(`[lark/${bot.appId}] resolver delivery id=${delivery.id} agent=${delivery.agent} message=${result.message.id}`);
+                }
+                if (tag === 'new' && larkMessage?.message_id) {
+                  const emojiType = deliveryReactionEmojiType();
+                  try {
+                    const client = createLarkApiClient(bot.appId, bot.appSecret);
+                    const reaction = await addMessageReaction({
+                      client,
+                      messageId: larkMessage.message_id,
+                      emojiType,
+                    });
+                    log.log(`[lark/${bot.appId}] added reaction emoji=${emojiType} message=${larkMessage.message_id} reaction=${reaction.reactionId ?? '-'}`);
+                  } catch (err) {
+                    log.warn(`[lark/${bot.appId}] add reaction failed message=${larkMessage.message_id}: ${apiErrorMessage(err)}`);
+                  }
+                }
+              }
+            }
+          } else if (result.status === 'skipped') {
+            log.log(`[lark/${bot.appId}] ingest skipped reason=${result.reason}`);
+          }
+        } catch (err) {
+          log.error(`[lark/${bot.appId}] ingest error:`, err);
+        }
+      }
+    },
+  });
+
+  const applyBots = (bots: LarkCredential[]): LarkReloadResult => {
+    const nextByApp = new Map(bots.map((bot) => [bot.appId, bot]));
+    const started: string[] = [];
+    const stopped: string[] = [];
+    const restarted: string[] = [];
+    const pending = new Map<string, { bot: LarkCredential; handle: LarkDaemonHandle; fingerprint: string; replacing: boolean }>();
+
+    try {
+      for (const bot of bots) {
+        const fingerprint = credentialFingerprint(bot);
+        const current = active.get(bot.appId);
+        if (current?.fingerprint === fingerprint) continue;
+        const handle = startBot(bot);
+        pending.set(bot.appId, { bot, handle, fingerprint, replacing: Boolean(current) });
+      }
+    } catch (err) {
+      for (const entry of pending.values()) entry.handle.stop();
+      return { ok: false, bots: activeAppIds(), error: err instanceof Error ? err.message : String(err) };
+    }
+
+    for (const [appId, current] of active.entries()) {
+      const pendingReplacement = pending.get(appId);
+      if (!nextByApp.has(appId) || pendingReplacement) {
+        current.handle.stop();
+        stopped.push(appId);
+        active.delete(appId);
+      }
+    }
+
+    for (const [appId, entry] of pending.entries()) {
+      active.set(appId, entry);
+      if (entry.replacing) restarted.push(appId);
+      else started.push(appId);
+    }
+
+    afterSuccessfulScan(bots);
+    return { ok: true, bots: activeAppIds(), started, stopped, restarted };
+  };
+
+  const reload = (): LarkReloadResult => {
+    let bots: LarkCredential[];
+    try {
+      bots = loadBotsForReload();
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      log.warn(`[lark] reload skipped: ${error}`);
+      return { ok: false, bots: activeAppIds(), error };
+    }
+    if (bots.length === 0) {
+      log.log('[lark] no bots configured, skipping lark integration');
+    } else {
+      log.log(`[lark] reloading ${bots.length} bot(s) on server policy=${policy}`);
+    }
+    return applyBots(bots);
+  };
+
+  const initial = reload();
+  if (!initial.ok) {
+    log.warn(`[lark] initial load failed: ${initial.error}`);
+  }
+
+  return {
+    get handles() {
+      return activeHandles();
+    },
+    reload,
+    stop() {
+      const handles = activeHandles();
+      for (const h of handles) h.stop();
+      active.clear();
+      log.log(`[lark] stopped ${handles.length} bot(s)`);
+    },
+  };
+}