@controlflow-ai/daemon 0.1.2 → 0.1.4

package/src/lark/server-integration.ts

@@ -1,8 +1,48 @@
 import { MessageStore } from '../db.js';
-import { boundAgents, loadLarkCredentials, type LarkCredential } from './credentials.js';
-import { extractMentionOpenIds, ingestLarkMessage, type LarkMessageEnvelope } from './event-router.js';
+import { homeDir } from '../config.js';
+import { boundAgents, defaultLarkConfigPath, loadLarkCredentials, type LarkCredential } from './credentials.js';
+import { extractLarkImageResources, extractMentionOpenIds, ingestLarkMessage, type LarkImageResource, type LarkMessageEnvelope } from './event-router.js';
+import { countInboundParseFailures, countProbeInboundEvents, countProviderInboundEvents, latestInboundEventSummary, latestProbeInboundEventSummary, storeInboundEvent, type InboundRawEventSummary } from './inbound-events.js';
 import type { ReceivePolicy } from './dispatcher.js';
-import { addMessageReaction, createLarkApiClient, getChatInfo, getChatMembers, startLarkDaemon, type LarkDaemonHandle } from './ws-daemon.js';
+import { addMessageReaction, buildLarkEventRawBody, createLarkApiClient, getChatInfo, getChatMembers, startLarkDaemon, type LarkDaemonHandle, type LarkEventCallback, type LarkWebSocketLifecycleCallback } from './ws-daemon.js';
+import type { MessageDelivery } from '../types.js';
+import { larkBotNeedsRestart } from '../messaging-status.js';
+
+async function readableToUint8Array(stream: NodeJS.ReadableStream): Promise<Uint8Array> {
+  const chunks: Buffer[] = [];
+  return new Promise((resolve, reject) => {
+    stream.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    stream.on('end', () => resolve(Buffer.concat(chunks)));
+    stream.on('error', reject);
+  });
+}
+
+async function larkDownloadToUint8Array(raw: unknown): Promise<Uint8Array> {
+  if (raw instanceof Uint8Array) return raw;
+  if (Buffer.isBuffer(raw)) return raw;
+  if (raw && typeof raw === 'object') {
+    const record = raw as { getReadableStream?: () => NodeJS.ReadableStream; data?: unknown };
+    if (typeof record.getReadableStream === 'function') return readableToUint8Array(record.getReadableStream());
+    if (record.data instanceof Uint8Array) return record.data;
+    if (Buffer.isBuffer(record.data)) return record.data;
+  }
+  throw new Error('unexpected Lark image download response');
+}
+
+async function downloadLarkImage(input: { appId: string; appSecret: string; resource: LarkImageResource }): Promise<Uint8Array> {
+  const client = createLarkApiClient(input.appId, input.appSecret) as unknown as {
+    im: { v1?: { image?: { get(input: { path: { image_key: string } }): Promise<unknown> } } };
+  };
+  if (!client.im.v1?.image?.get) throw new Error('Lark SDK image download API is unavailable');
+  return larkDownloadToUint8Array(await client.im.v1.image.get({ path: { image_key: input.resource.fileKey } }));
+}
+
+export interface LarkDeliveryNotifyResult {
+  deliveries: number;
+  target_connections: number;
+  open_sockets: number;
+  websocket_frames: number;
+}
 
 export interface LarkServerIntegrationOptions {
   /** Shared MessageStore for DB operations (caller owns lifecycle). */
@@ -11,16 +51,94 @@ export interface LarkServerIntegrationOptions {
   botOpenIdByApp?: Map<string, string>;
   logger?: Partial<Pick<Console, 'log' | 'warn' | 'error'>>;
   configPath?: string;
+  dbPath?: string;
   startDaemon?: typeof startLarkDaemon;
+  deliveryNotifier?: {
+    notifyDeliveries(deliveries: MessageDelivery[]): LarkDeliveryNotifyResult;
+  };
+  syncRoomMetadata?: boolean;
+  sendDeliveryReaction?: boolean;
 }
 
 export type LarkReloadResult =
   | { ok: true; bots: string[]; started: string[]; stopped: string[]; restarted: string[] }
   | { ok: false; bots: string[]; error: string };
 
+export type LarkRestartResult =
+  | { ok: true; bots: string[]; restarted: string[]; missing: string[]; skipped_recent?: string[]; skipped_ineffective?: string[] }
+  | { ok: false; bots: string[]; restarted: string[]; missing: string[]; skipped_recent?: string[]; skipped_ineffective?: string[]; error: string };
+
+export interface LarkRestartStaleOptions {
+  staleAfterMs: number;
+  now?: number;
+  minRestartIntervalMs?: number;
+}
+
+export interface LarkProbeEventInput {
+  appId: string;
+  envelope?: 'im.message.receive_v1' | 'card.action.trigger' | string;
+  data: unknown;
+}
+
+export interface LarkProbeEventResult {
+  app_id: string;
+  envelope: string;
+  raw_event_id: string;
+  inserted: boolean;
+  duplicate: boolean;
+  parse_ok: 0 | 1;
+  handled: boolean;
+}
+
+export interface LarkBotRuntimeStatus {
+  app_id: string;
+  agent: string | null;
+  label: string | null;
+  bot_open_id_known: boolean;
+  authorized_user_count: number;
+  runtime_home: string;
+  config_path: string;
+  db_path: string | null;
+  ws_state: string | null;
+  ws_last_connect_at: string | null;
+  ws_next_connect_at: string | null;
+  ws_reconnect_attempts: number | null;
+  ws_last_event_at: string | null;
+  ws_last_event_type: string | null;
+  ws_last_error: string | null;
+  restart_count: number;
+  last_restart_at: string | null;
+  last_restart_reason: string | null;
+  started_at: string;
+  event_count: number;
+  message_event_count: number;
+  provider_event_count: number;
+  provider_message_event_count: number;
+  last_event_at: string | null;
+  last_event_type: string | null;
+  last_provider_event_at: string | null;
+  last_provider_message_event_at: string | null;
+  last_message_event_at: string | null;
+  last_raw_event_id: string | null;
+  last_ingest_status: string | null;
+  last_delivery_count: number | null;
+  last_delivery_notify: LarkDeliveryNotifyResult | null;
+  db_event_count: number;
+  db_provider_event_count: number;
+  db_probe_event_count: number;
+  db_parse_error_count: number;
+  db_last_event: InboundRawEventSummary | null;
+  db_last_probe_event: InboundRawEventSummary | null;
+  last_error: string | null;
+}
+
 export interface LarkServerIntegrationResult {
   handles: LarkDaemonHandle[];
+  status(): LarkBotRuntimeStatus[];
   reload(): LarkReloadResult;
+  restart(appIds?: string[]): LarkRestartResult;
+  restartStale(options: LarkRestartStaleOptions): LarkRestartResult;
+  injectProbeEvent(input: LarkProbeEventInput): Promise<LarkProbeEventResult>;
   stop(): void;
 }
 
@@ -51,6 +169,13 @@ function mentionsBotLabel(envelope: LarkMessageEnvelope, bot: LarkCredential): b
   return (envelope.message?.mentions ?? []).some((mention) => mention.name?.trim().toLowerCase() === expected);
 }
 
+function mentionOpenIdForBotLabel(envelope: LarkMessageEnvelope, bot: LarkCredential): string | null {
+  if (!bot.label) return null;
+  const expected = bot.label.trim().toLowerCase();
+  if (!expected) return null;
+  const mention = (envelope.message?.mentions ?? []).find((entry) => entry.name?.trim().toLowerCase() === expected);
+  return mention?.id?.open_id?.trim() || null;
+}
 
 function senderUnionId(envelope: LarkMessageEnvelope): string | null {
   return envelope.sender?.sender_id?.union_id?.trim() || null;
@@ -64,6 +189,29 @@ function deliveryReactionEmojiType(): string {
   return process.env.PAL_LARK_ACTION_REACTION_EMOJI?.trim() || 'Typing';
 }
 
+function addSingleAgentBotMentionMapping(input: {
+  mappings: Map<string, string>;
+  bot: LarkCredential;
+  botOpenIdByApp: Map<string, string>;
+  fallbackBotOpenId?: string | null;
+  envelope?: LarkMessageEnvelope;
+}): void {
+  const agents = boundAgents(input.bot);
+  if (agents.length !== 1) return;
+  const openId = input.botOpenIdByApp.get(input.bot.appId)
+    ?? input.bot.botOpenId
+    ?? (input.envelope ? mentionOpenIdForBotLabel(input.envelope, input.bot) : null)
+    ?? input.fallbackBotOpenId
+    ?? null;
+  if (openId) input.mappings.set(openId, agents[0]!);
+}
+
+function hasDeliveryForAgents(deliveries: Array<{ agent: string }>, agents: string[]): boolean {
+  if (agents.length === 0) return false;
+  const agentSet = new Set(agents);
+  return deliveries.some((delivery) => agentSet.has(delivery.agent));
+}
+
 function apiErrorMessage(err: unknown): string {
   if (err instanceof Error) {
     const responseData = (err as Error & { response?: { data?: unknown } }).response?.data;
@@ -78,6 +226,78 @@ function apiErrorMessage(err: unknown): string {
   return String(err);
 }
 
+function timestampFromMs(value: number | undefined): string | null {
+  return value ? new Date(value).toISOString() : null;
+}
+
+function parseInboundReceivedAt(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const normalized = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)
+    ? `${value.replace(' ', 'T')}Z`
+    : value;
+  const time = Date.parse(normalized);
+  return Number.isFinite(time) ? time : null;
+}
+
+function hasProviderEventAfterRestart(status: { db_last_event?: InboundRawEventSummary | null; last_restart_at?: string | null }): boolean {
+  const lastRestartAt = parseInboundReceivedAt(status.last_restart_at);
+  const lastProviderEventAt = parseInboundReceivedAt(status.db_last_event?.received_at);
+  return lastRestartAt !== null && lastProviderEventAt !== null && lastProviderEventAt > lastRestartAt;
+}
+
+function isLocalProbeEvent(storeResult: Pick<LarkProbeEventResult, 'raw_event_id'> | { event_id?: string; event_type?: string }): boolean {
+  const eventId = 'raw_event_id' in storeResult ? storeResult.raw_event_id : storeResult.event_id;
+  const eventType = 'event_type' in storeResult ? storeResult.event_type : undefined;
+  return Boolean(eventId?.startsWith('pal.probe:') || eventType?.startsWith('pal.probe.'));
+}
+
+function isLocalProbeChatId(chatId: string | null | undefined): boolean {
+  return Boolean(chatId?.includes('pal_probe') || chatId?.startsWith('oc_probe'));
+}
+
+function larkWsConnectionStatus(handle: LarkDaemonHandle): Pick<LarkBotRuntimeStatus, 'ws_state' | 'ws_last_connect_at' | 'ws_next_connect_at' | 'ws_reconnect_attempts'> {
+  try {
+    const status = (handle.wsClient as unknown as {
+      getConnectionStatus?: () => {
+        state?: string;
+        lastConnectTime?: number;
+        nextConnectTime?: number;
+        reconnectAttempts?: number;
+      };
+    }).getConnectionStatus?.();
+    return {
+      ws_state: status?.state ?? null,
+      ws_last_connect_at: timestampFromMs(status?.lastConnectTime),
+      ws_next_connect_at: timestampFromMs(status?.nextConnectTime),
+      ws_reconnect_attempts: typeof status?.reconnectAttempts === 'number' ? status.reconnectAttempts : null,
+    };
+  } catch {
+    return {
+      ws_state: null,
+      ws_last_connect_at: null,
+      ws_next_connect_at: null,
+      ws_reconnect_attempts: null,
+    };
+  }
+}
+
+function notifyLarkDeliveries(input: {
+  notifier: LarkServerIntegrationOptions['deliveryNotifier'];
+  deliveries: MessageDelivery[];
+  appId: string;
+  log: Pick<Console, 'log' | 'warn'>;
+}): LarkDeliveryNotifyResult | null {
+  if (!input.notifier) return null;
+  try {
+    const notify = input.notifier.notifyDeliveries(input.deliveries);
+    input.log.log(`[lark/${input.appId}] notify deliveries=${notify.deliveries} target_connections=${notify.target_connections} open_sockets=${notify.open_sockets} websocket_frames=${notify.websocket_frames}`);
+    return notify;
+  } catch (err) {
+    input.log.warn(`[lark/${input.appId}] notify failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
 async function syncLarkRoomMetadata(input: {
   bot: LarkCredential;
   chatId: string;
@@ -155,6 +375,7 @@ async function syncExistingLarkGroupRooms(input: {
     seen.add(key);
     const bot = botsByApp.get(mapping.app_id);
     if (!bot) continue;
+    if (isLocalProbeChatId(mapping.external_chat_id)) continue;
     await syncLarkRoomMetadata({
       bot,
       chatId: mapping.external_chat_id,
@@ -214,7 +435,12 @@ export function startLarkOnServer(options: LarkServerIntegrationOptions): LarkSe
   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 runtimeHome = homeDir();
+  const configPath = options.configPath ?? defaultLarkConfigPath();
+  const dbPath = options.dbPath ?? null;
+  const syncRoomMetadataEnabled = options.syncRoomMetadata ?? true;
+  const sendDeliveryReactionEnabled = options.sendDeliveryReaction ?? true;
+  const active = new Map<string, { bot: LarkCredential; handle: LarkDaemonHandle; fingerprint: string; status: LarkBotRuntimeStatus; onEvent: LarkEventCallback; onLifecycle: LarkWebSocketLifecycleCallback }>();
 
   const activeBots = (): LarkCredential[] => Array.from(active.values()).map((entry) => entry.bot);
   const activeHandles = (): LarkDaemonHandle[] => Array.from(active.values()).map((entry) => entry.handle);
@@ -247,135 +473,280 @@ export function startLarkOnServer(options: LarkServerIntegrationOptions): LarkSe
     });
   };
 
-  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 identity = await resolveSenderUnionId({ bot, envelope: larkEnvelope, store: msgStore });
-          if (identity.status === 'pending') {
-            msgStore.recordPendingInboundEvent({ rawEventId: storeResult.event_id, provider: 'lark', reason: 'missing_lark_sender_user_id', error: identity.reason });
-            log.warn(`[lark/${bot.appId}] sender union_id lookup pending: ${identity.reason}`);
-            return;
-          }
-          if (identity.status !== 'resolved' || !msgStore.isLarkAuthorizedUser(identity.unionId)) {
-            log.log(`[lark/${bot.appId}] business ingest skipped sender_union=${identity.status === 'resolved' ? identity.unionId : '-'} authorized=false`);
-            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 startBot = (bot: LarkCredential): { handle: LarkDaemonHandle; status: LarkBotRuntimeStatus; onEvent: LarkEventCallback; onLifecycle: LarkWebSocketLifecycleCallback } => {
+    const restartState = msgStore.getLarkWebsocketRestartState(bot.appId);
+    const status: LarkBotRuntimeStatus = {
+      app_id: bot.appId,
+      agent: bot.agent?.trim() || null,
+      label: bot.label?.trim() || null,
+      bot_open_id_known: Boolean(bot.botOpenId?.trim() || botOpenIdByApp.get(bot.appId)),
+      authorized_user_count: 0,
+      runtime_home: runtimeHome,
+      config_path: configPath,
+      db_path: dbPath,
+      ws_state: null,
+      ws_last_connect_at: null,
+      ws_next_connect_at: null,
+      ws_reconnect_attempts: null,
+      ws_last_event_at: null,
+      ws_last_event_type: null,
+      ws_last_error: null,
+      restart_count: restartState?.restart_count ?? 0,
+      last_restart_at: restartState?.last_restart_at ?? null,
+      last_restart_reason: restartState?.last_restart_reason ?? null,
+      started_at: new Date().toISOString(),
+      event_count: 0,
+      message_event_count: 0,
+      provider_event_count: 0,
+      provider_message_event_count: 0,
+      last_event_at: null,
+      last_event_type: null,
+      last_provider_event_at: null,
+      last_provider_message_event_at: null,
+      last_message_event_at: null,
+      last_raw_event_id: null,
+      last_ingest_status: null,
+      last_delivery_count: null,
+      last_delivery_notify: null,
+      db_event_count: 0,
+      db_provider_event_count: 0,
+      db_probe_event_count: 0,
+      db_parse_error_count: 0,
+      db_last_event: null,
+      db_last_probe_event: null,
+      last_error: null,
+    };
+
+    const onLifecycle: LarkWebSocketLifecycleCallback = (event) => {
+      status.ws_last_event_at = new Date().toISOString();
+      status.ws_last_event_type = event.type;
+      status.ws_last_error = event.error ?? null;
+    };
+
+    const onEvent: LarkEventCallback = async ({ envelope, data, storeResult }) => {
+        const isProbe = isLocalProbeEvent(storeResult);
+        status.event_count += 1;
+        status.last_event_at = new Date().toISOString();
+        status.last_event_type = envelope;
+        status.last_raw_event_id = storeResult.event_id;
+        status.last_error = null;
+        if (!isProbe) {
+          status.provider_event_count += 1;
+          status.last_provider_event_at = status.last_event_at;
+        }
+        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') {
+          status.message_event_count += 1;
+          status.last_message_event_at = status.last_event_at;
+          if (!isProbe) {
+            status.provider_message_event_count += 1;
+            status.last_provider_message_event_at = status.last_event_at;
           }
-          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)}`);
-              }
+          status.last_ingest_status = null;
+          status.last_delivery_count = null;
+          status.last_delivery_notify = null;
+          try {
+            const larkEnvelope = data as LarkMessageEnvelope;
+            const identity = await resolveSenderUnionId({ bot, envelope: larkEnvelope, store: msgStore });
+            if (identity.status === 'pending') {
+              msgStore.recordPendingInboundEvent({ rawEventId: storeResult.event_id, provider: 'lark', reason: 'missing_lark_sender_user_id', error: identity.reason });
+              status.last_ingest_status = 'pending_sender_identity';
+              status.last_delivery_count = 0;
+              status.last_delivery_notify = null;
+              log.warn(`[lark/${bot.appId}] sender union_id lookup pending: ${identity.reason}`);
+              return;
             }
-            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();
+            if (identity.status !== 'resolved' || !msgStore.isLarkAuthorizedUser(identity.unionId)) {
+              status.last_ingest_status = 'skipped_unauthorized_sender';
+              status.last_delivery_count = 0;
+              status.last_delivery_notify = null;
+              log.log(`[lark/${bot.appId}] business ingest skipped sender_union=${identity.status === 'resolved' ? identity.unionId : '-'} authorized=false`);
+              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>();
+            for (const candidate of activeBots()) {
+              addSingleAgentBotMentionMapping({
+                mappings: recipientByMentionOpenId,
+                bot: candidate,
+                botOpenIdByApp,
+                fallbackBotOpenId: candidate.appId === bot.appId ? inferredBotOpenId : null,
+                envelope: larkEnvelope,
+              });
+            }
+            const labelMentionedThisBot = mentionsBotLabel(larkEnvelope, bot);
+            const labelMentionedAnyKnownBot = activeBots().some((candidate) => mentionsBotLabel(larkEnvelope, candidate));
+            if (labelMentionedAnyKnownBot && !labelMentionedThisBot) {
+              status.last_ingest_status = 'skipped_other_bot_label';
+              status.last_delivery_count = 0;
+              status.last_delivery_notify = null;
+              log.log(`[lark/${bot.appId}] label mention targets another bot, skipping ingest`);
+              return;
+            }
+            const hasReplyContext = Boolean(larkEnvelope.message?.root_id || larkEnvelope.message?.parent_id);
+            const recipientOverride = agents.length === 1 && (
+              larkEnvelope.message?.chat_type === 'p2p' ||
+              labelMentionedThisBot ||
+              hasReplyContext
+            )
+              ? 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';
+              status.last_ingest_status = `ok_${tag}`;
+              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 (!result.deduped) {
+                for (const resource of extractLarkImageResources(larkEnvelope)) {
                   try {
-                    const client = createLarkApiClient(bot.appId, bot.appSecret);
-                    const reaction = await addMessageReaction({
-                      client,
-                      messageId: larkMessage.message_id,
-                      emojiType,
+                    const content = await downloadLarkImage({ appId: bot.appId, appSecret: bot.appSecret, resource });
+                    const attachment = msgStore.addMessageAttachment(result.message.id, {
+                      kind: 'image',
+                      mimeType: resource.mimeType,
+                      filename: resource.filename,
+                      content,
+                      sourceProvider: 'lark',
+                      sourceRef: resource.fileKey,
                     });
-                    log.log(`[lark/${bot.appId}] added reaction emoji=${emojiType} message=${larkMessage.message_id} reaction=${reaction.reactionId ?? '-'}`);
+                    log.log(`[lark/${bot.appId}] stored image attachment=${attachment.id} message=${result.message.id} bytes=${attachment.size_bytes}`);
                   } catch (err) {
-                    log.warn(`[lark/${bot.appId}] add reaction failed message=${larkMessage.message_id}: ${apiErrorMessage(err)}`);
+                    log.warn(`[lark/${bot.appId}] image download failed message=${result.message.id}: ${apiErrorMessage(err)}`);
                   }
                 }
               }
+              if (larkMessage?.chat_id && !isProbe) {
+                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,
+                  });
+                  if (syncRoomMetadataEnabled) {
+                    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);
+                status.last_delivery_count = deliveries.length;
+                if (deliveries.length === 0) {
+                  status.last_delivery_notify = null;
+                  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 (result.deduped) {
+                    status.last_delivery_notify = null;
+                    log.log(`[lark/${bot.appId}] duplicate event did not re-notify deliveries message=${result.message.id}`);
+                  } else {
+                    status.last_delivery_notify = notifyLarkDeliveries({
+                      notifier: options.deliveryNotifier,
+                      deliveries,
+                      appId: bot.appId,
+                      log,
+                    });
+                  }
+                  if (!isProbe && sendDeliveryReactionEnabled && hasDeliveryForAgents(deliveries, agents) && 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') {
+              status.last_ingest_status = `skipped_${result.reason}`;
+              status.last_delivery_count = 0;
+              status.last_delivery_notify = null;
+              log.log(`[lark/${bot.appId}] ingest skipped reason=${result.reason}`);
             }
-          } else if (result.status === 'skipped') {
-            log.log(`[lark/${bot.appId}] ingest skipped reason=${result.reason}`);
+          } catch (err) {
+            status.last_ingest_status = 'error';
+            status.last_delivery_count = 0;
+            status.last_delivery_notify = null;
+            status.last_error = err instanceof Error ? err.message : String(err);
+            log.error(`[lark/${bot.appId}] ingest error:`, err);
           }
-        } catch (err) {
-          log.error(`[lark/${bot.appId}] ingest error:`, err);
         }
-      }
-    },
-  });
+      };
+
+    const handle = startDaemon({
+      appId: bot.appId,
+      appSecret: bot.appSecret,
+      db: msgStore.db,
+      logger: { info: log.log, warn: log.warn, error: log.error },
+      onEvent,
+      onLifecycle,
+    });
+    return { handle, status, onEvent, onLifecycle };
+  };
 
   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 }>();
+    const pending = new Map<string, { bot: LarkCredential; handle: LarkDaemonHandle; fingerprint: string; status: LarkBotRuntimeStatus; onEvent: LarkEventCallback; onLifecycle: LarkWebSocketLifecycleCallback; 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) });
+        const startedBot = startBot(bot);
+        pending.set(bot.appId, {
+          bot,
+          handle: startedBot.handle,
+          fingerprint,
+          status: startedBot.status,
+          onEvent: startedBot.onEvent,
+          onLifecycle: startedBot.onLifecycle,
+          replacing: Boolean(current),
+        });
       }
     } catch (err) {
       for (const entry of pending.values()) entry.handle.stop();
@@ -392,7 +763,14 @@ export function startLarkOnServer(options: LarkServerIntegrationOptions): LarkSe
     }
 
     for (const [appId, entry] of pending.entries()) {
-      active.set(appId, entry);
+      active.set(appId, {
+        bot: entry.bot,
+        handle: entry.handle,
+        fingerprint: entry.fingerprint,
+        status: entry.status,
+        onEvent: entry.onEvent,
+        onLifecycle: entry.onLifecycle,
+      });
       if (entry.replacing) restarted.push(appId);
       else started.push(appId);
     }
@@ -418,6 +796,123 @@ export function startLarkOnServer(options: LarkServerIntegrationOptions): LarkSe
     return applyBots(bots);
   };
 
+  const restart = (appIds?: string[]): LarkRestartResult => restartWithReason(appIds, 'manual');
+
+  const restartWithReason = (appIds: string[] | undefined, reason: string): LarkRestartResult => {
+    const requested = appIds && appIds.length > 0 ? Array.from(new Set(appIds.map((id) => id.trim()).filter(Boolean))) : activeAppIds();
+    const missing = requested.filter((appId) => !active.has(appId));
+    const restarted: string[] = [];
+    for (const appId of requested) {
+      const current = active.get(appId);
+      if (!current) continue;
+      let next: { handle: LarkDaemonHandle; status: LarkBotRuntimeStatus; onEvent: LarkEventCallback; onLifecycle: LarkWebSocketLifecycleCallback };
+      try {
+        next = startBot(current.bot);
+      } catch (err) {
+        return {
+          ok: false,
+          bots: activeAppIds(),
+          restarted,
+          missing,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+      const restartedAt = new Date().toISOString();
+      let restartState: ReturnType<MessageStore['recordLarkWebsocketRestart']>;
+      try {
+        restartState = msgStore.recordLarkWebsocketRestart({ appId, restartedAt, reason });
+      } catch (err) {
+        next.handle.stop();
+        return {
+          ok: false,
+          bots: activeAppIds(),
+          restarted,
+          missing,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+      next.status.restart_count = restartState.restart_count;
+      next.status.last_restart_at = restartState.last_restart_at;
+      next.status.last_restart_reason = restartState.last_restart_reason;
+      current.handle.stop();
+      active.set(appId, {
+        bot: current.bot,
+        handle: next.handle,
+        fingerprint: current.fingerprint,
+        status: next.status,
+        onEvent: next.onEvent,
+        onLifecycle: next.onLifecycle,
+      });
+      restarted.push(appId);
+    }
+    if (restarted.length > 0) {
+      afterSuccessfulScan(restarted.map((appId) => active.get(appId)?.bot).filter((bot): bot is LarkCredential => Boolean(bot)));
+    }
+    log.log(`[lark] restarted ${restarted.length} bot websocket(s)${missing.length > 0 ? ` missing=${missing.join(',')}` : ''}`);
+    return { ok: true, bots: activeAppIds(), restarted, missing };
+  };
+
+  const restartStale = (restartOptions: LarkRestartStaleOptions): LarkRestartResult => {
+    const now = restartOptions.now ?? Date.now();
+    const staleAfterMs = restartOptions.staleAfterMs;
+    const minRestartIntervalMs = restartOptions.minRestartIntervalMs ?? 0;
+    if (!Number.isFinite(staleAfterMs) || staleAfterMs <= 0) {
+      return { ok: false, bots: activeAppIds(), restarted: [], missing: [], error: 'staleAfterMs must be positive' };
+    }
+    if (!Number.isFinite(minRestartIntervalMs) || minRestartIntervalMs < 0) {
+      return { ok: false, bots: activeAppIds(), restarted: [], missing: [], error: 'minRestartIntervalMs must be zero or positive' };
+    }
+    const restartAppIds: string[] = [];
+    const skippedRecent: string[] = [];
+    const skippedIneffective: string[] = [];
+    for (const entry of active.values()) {
+      const dbProviderEventCount = countProviderInboundEvents(msgStore.db, entry.bot.appId);
+      const status = {
+        ...entry.status,
+        db_event_count: dbProviderEventCount,
+        db_provider_event_count: dbProviderEventCount,
+        db_probe_event_count: countProbeInboundEvents(msgStore.db, entry.bot.appId),
+        db_parse_error_count: countInboundParseFailures(msgStore.db, entry.bot.appId),
+        db_last_event: latestInboundEventSummary(msgStore.db, entry.bot.appId),
+        db_last_probe_event: latestProbeInboundEventSummary(msgStore.db, entry.bot.appId),
+        ...larkWsConnectionStatus(entry.handle),
+      };
+      if (!larkBotNeedsRestart(status, { now, staleAfterMs })) continue;
+      const lastRestartAt = parseInboundReceivedAt(entry.status.last_restart_at);
+      if (lastRestartAt !== null && minRestartIntervalMs > 0 && now - lastRestartAt < minRestartIntervalMs) {
+        skippedRecent.push(entry.bot.appId);
+        continue;
+      }
+      if (
+        entry.status.last_restart_reason === 'auto_stale'
+        && (entry.status.restart_count ?? 0) > 0
+        && lastRestartAt !== null
+        && !hasProviderEventAfterRestart(status)
+      ) {
+        skippedIneffective.push(entry.bot.appId);
+        continue;
+      }
+      restartAppIds.push(entry.bot.appId);
+    }
+    if (restartAppIds.length === 0) {
+      return {
+        ok: true,
+        bots: activeAppIds(),
+        restarted: [],
+        missing: [],
+        ...(skippedRecent.length > 0 ? { skipped_recent: skippedRecent } : {}),
+        ...(skippedIneffective.length > 0 ? { skipped_ineffective: skippedIneffective } : {}),
+      };
+    }
+    log.warn(`[lark] unhealthy/stale inbound state for ${restartAppIds.join(',')}; restarting websocket(s)`);
+    const result = restartWithReason(restartAppIds, 'auto_stale');
+    return {
+      ...result,
+      ...(skippedRecent.length > 0 ? { skipped_recent: skippedRecent } : {}),
+      ...(skippedIneffective.length > 0 ? { skipped_ineffective: skippedIneffective } : {}),
+    };
+  };
+
   const initial = reload();
   if (!initial.ok) {
     log.warn(`[lark] initial load failed: ${initial.error}`);
@@ -427,7 +922,60 @@ export function startLarkOnServer(options: LarkServerIntegrationOptions): LarkSe
     get handles() {
       return activeHandles();
     },
+    status() {
+      return Array.from(active.values()).map((entry) => {
+        const dbProviderEventCount = countProviderInboundEvents(msgStore.db, entry.bot.appId);
+        return {
+          ...entry.status,
+          db_event_count: dbProviderEventCount,
+          db_provider_event_count: dbProviderEventCount,
+          db_probe_event_count: countProbeInboundEvents(msgStore.db, entry.bot.appId),
+          db_parse_error_count: countInboundParseFailures(msgStore.db, entry.bot.appId),
+          db_last_event: latestInboundEventSummary(msgStore.db, entry.bot.appId),
+          db_last_probe_event: latestProbeInboundEventSummary(msgStore.db, entry.bot.appId),
+          agent: entry.bot.agent?.trim() || null,
+          label: entry.bot.label?.trim() || null,
+          bot_open_id_known: Boolean(entry.bot.botOpenId?.trim() || botOpenIdByApp.get(entry.bot.appId)),
+          authorized_user_count: msgStore.listLarkAuthorizedUsers().length,
+          ...larkWsConnectionStatus(entry.handle),
+        };
+      });
+    },
     reload,
+    restart,
+    restartStale,
+    async injectProbeEvent(input: LarkProbeEventInput): Promise<LarkProbeEventResult> {
+      const appId = input.appId.trim();
+      const entry = active.get(appId);
+      if (!entry) throw new Error(`Lark bot is not active: ${appId}`);
+      const envelope = input.envelope ?? 'im.message.receive_v1';
+      const raw = JSON.parse(buildLarkEventRawBody(envelope, input.data)) as {
+        header?: { event_id?: string; event_type?: string };
+      };
+      raw.header = raw.header ?? {};
+      raw.header.event_type = `pal.probe.${envelope}`;
+      raw.header.event_id = raw.header.event_id ? `pal.probe:${raw.header.event_id}` : `pal.probe:${envelope}:${crypto.randomUUID()}`;
+      const rawBody = JSON.stringify(raw);
+      const storeResult = await storeInboundEvent(msgStore.db, { appId, rawBody });
+      if (!storeResult.duplicate) {
+        await entry.onEvent({
+          appId,
+          envelope,
+          data: input.data,
+          rawBody,
+          storeResult,
+        });
+      }
+      return {
+        app_id: appId,
+        envelope,
+        raw_event_id: storeResult.event_id,
+        inserted: storeResult.inserted,
+        duplicate: storeResult.duplicate,
+        parse_ok: storeResult.parse_ok,
+        handled: !storeResult.duplicate,
+      };
+    },
     stop() {
       const handles = activeHandles();
       for (const h of handles) h.stop();