feat: add Lark long-connection runtime mode

Start a Lark WS client from configured app credentials so local testing works without public webhooks while preserving the existing callback path and event handling behavior.

Author: Joshua Chittick

.env.example

@@ -10,3 +10,4 @@
 # Optional default Lark app credentials for action API
 # LARK_APP_ID=
 # LARK_APP_SECRET=
+# LARK_LONG_CONNECTION=true

README.md

@@ -51,6 +51,7 @@ Settings UI can be accessible via http://127.0.0.1:9293 or use `/setting` comman
 
 For Lark event subscriptions (Open Platform app), use callback endpoint: `POST /api/lark/event`.
 In Lark chats, send `/setting` to get a settings card and open local settings quickly.
+By default Ode also starts Lark long-connection mode (WS) when Lark app credentials are configured, so local testing can work without a public callback URL. Set `LARK_LONG_CONNECTION=false` to disable it.
 
 ![Channel](static/channel-setting.png)
 *Run `@bot /setting` to trigger setting dialog.*

README.zh-CN.md

@@ -49,6 +49,7 @@ ode
 
 Lark 开放平台事件订阅回调地址可使用：`POST /api/lark/event`。
 在 Lark 聊天里发送 `/setting` 可收到设置卡片并快速打开本地设置页面。
+默认情况下，只要配置了 Lark 凭据，Ode 也会启动 Lark 长连接（WS）模式，因此本地测试不需要公网回调地址。可通过 `LARK_LONG_CONNECTION=false` 关闭。
 
 ![Channel](static/channel-setting.png)
 *Run `@bot /setting` to trigger setting dialog.*

bun.lock

@@ -29,6 +29,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.55.0",
     "@opencode-ai/sdk": "^1.1.25",
     "@slack/bolt": "^4.6.0",
     "@slack/socket-mode": "^2.0.5",

package.json

@@ -1,5 +1,6 @@
 import { createAgentAdapter } from "@/agents/adapter";
 import type { OpenCodeMessageContext } from "@/agents/types";
+import * as Lark from "@larksuiteoapi/node-sdk";
 import {
   getChannelSystemMessage,
   getGitHubInfoForUser,
@@ -52,6 +53,7 @@ type LarkBotInfoResponse = {
 const tenantTokenCache = new Map<string, { token: string; expiresAt: number }>();
 const botOpenIdCache = new Map<string, string>();
 const sentMessageThreadMap = new Map<string, { channelId: string; threadId: string }>();
+const wsClientRegistry = new Map<string, unknown>();
 
 function getLarkCredentialsForChannel(channelId: string): LarkCredentials | null {
   const channel = channelId.trim();
@@ -444,42 +446,37 @@ type LarkIncomingEnvelope = {
   };
 };
 
-export async function handleLarkEventPayload(payload: unknown): Promise<{ status: number; body: Record<string, unknown> }> {
-  if (!payload || typeof payload !== "object") {
-    return { status: 400, body: { ok: false, error: "Invalid payload" } };
-  }
-
-  const envelope = payload as LarkIncomingEnvelope;
-  if (envelope.type === "url_verification" && typeof envelope.challenge === "string") {
-    return { status: 200, body: { challenge: envelope.challenge } };
-  }
+type LarkIncomingEvent = NonNullable<LarkIncomingEnvelope["event"]>;
 
-  if (envelope.header?.event_type !== "im.message.receive_v1") {
-    return { status: 200, body: { code: 0 } };
-  }
+function isLarkLongConnectionEnabled(): boolean {
+  const raw = process.env.LARK_LONG_CONNECTION?.trim().toLowerCase();
+  if (!raw) return true;
+  return !["0", "false", "off", "no"].includes(raw);
+}
 
-  const message = envelope.event?.message;
-  const senderOpenId = envelope.event?.sender?.sender_id?.open_id?.trim() || "";
+async function processLarkIncomingEvent(event: LarkIncomingEvent): Promise<void> {
+  const message = event.message;
+  const senderOpenId = event.sender?.sender_id?.open_id?.trim() || "";
   const channelId = message?.chat_id?.trim() || "";
   const messageId = message?.message_id?.trim() || "";
   const threadId = message?.root_id?.trim() || message?.parent_id?.trim() || messageId;
   const isThreadReply = Boolean(message?.root_id || message?.parent_id);
 
   if (!channelId || !messageId || !threadId || !senderOpenId) {
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   if (!isAuthorizedLarkChannel(channelId)) {
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   const botOpenId = await getBotOpenIdForChannel(channelId);
   if (botOpenId && senderOpenId === botOpenId) {
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   if (message?.message_type !== "text") {
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   const mentions = parseMentionedOpenIds(message?.mentions);
@@ -490,27 +487,27 @@ export async function handleLarkEventPayload(payload: unknown): Promise<{ status
 
   if (isSettingsCommand(text)) {
     await sendSettingsCard(channelId, threadId);
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   if (isThreadReply) {
     if (!isMentioned && !active) {
-      return { status: 200, body: { code: 0 } };
+      return;
     }
   } else if (!isMentioned) {
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   if (!text) {
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   if (isStopCommand(text)) {
     const stopped = await coreRuntime.handleStopCommand(channelId, threadId);
     if (stopped) {
       await sendMessage(channelId, threadId, "Request stopped.", true);
     }
-    return { status: 200, body: { code: 0 } };
+    return;
   }
 
   markThreadActive(channelId, threadId);
@@ -524,6 +521,98 @@ export async function handleLarkEventPayload(payload: unknown): Promise<{ status
     },
     text
   );
+}
+
+async function startLarkLongConnections(reason: string): Promise<void> {
+  if (!isLarkLongConnectionEnabled()) {
+    log.debug("Lark long connection disabled", { reason });
+    return;
+  }
+
+  const workspaces = getLarkAppCredentials();
+  const uniqueCredentials = new Map<string, { appId: string; appSecret: string }>();
+  for (const workspace of workspaces) {
+    if (!uniqueCredentials.has(workspace.appId)) {
+      uniqueCredentials.set(workspace.appId, {
+        appId: workspace.appId,
+        appSecret: workspace.appSecret,
+      });
+    }
+  }
+
+  for (const [appId, creds] of uniqueCredentials.entries()) {
+    if (wsClientRegistry.has(appId)) {
+      continue;
+    }
+
+    const eventDispatcher = new Lark.EventDispatcher({}).register({
+      "im.message.receive_v1": async (data: unknown) => {
+        try {
+          await processLarkIncomingEvent(data as LarkIncomingEvent);
+        } catch (error) {
+          log.warn("Failed to handle Lark long-connection message event", {
+            appId,
+            error: String(error),
+          });
+        }
+      },
+    });
+
+    const wsClient = new Lark.WSClient({
+      appId: creds.appId,
+      appSecret: creds.appSecret,
+      domain: Lark.Domain.Feishu,
+      loggerLevel: Lark.LoggerLevel.warn,
+    });
+
+    await Promise.resolve(
+      wsClient.start({
+        eventDispatcher,
+      })
+    );
+
+    wsClientRegistry.set(appId, wsClient);
+    log.info("Lark long connection started", { appId });
+  }
+}
+
+async function stopLarkLongConnections(reason: string): Promise<void> {
+  const entries = Array.from(wsClientRegistry.entries());
+  wsClientRegistry.clear();
+  for (const [appId, client] of entries) {
+    try {
+      const wsClient = client as { stop?: () => unknown | Promise<unknown> };
+      if (typeof wsClient.stop === "function") {
+        await Promise.resolve(wsClient.stop());
+      }
+      log.info("Lark long connection stopped", { appId, reason });
+    } catch (error) {
+      log.warn("Failed to stop Lark long connection", {
+        appId,
+        reason,
+        error: String(error),
+      });
+    }
+  }
+}
+
+export async function handleLarkEventPayload(payload: unknown): Promise<{ status: number; body: Record<string, unknown> }> {
+  if (!payload || typeof payload !== "object") {
+    return { status: 400, body: { ok: false, error: "Invalid payload" } };
+  }
+
+  const envelope = payload as LarkIncomingEnvelope;
+  if (envelope.type === "url_verification" && typeof envelope.challenge === "string") {
+    return { status: 200, body: { challenge: envelope.challenge } };
+  }
+
+  if (envelope.header?.event_type !== "im.message.receive_v1") {
+    return { status: 200, body: { code: 0 } };
+  }
+
+  if (envelope.event) {
+    await processLarkIncomingEvent(envelope.event);
+  }
 
   return { status: 200, body: { code: 0 } };
 }
@@ -543,12 +632,14 @@ export async function startLarkRuntime(reason: string): Promise<boolean> {
     reason,
     workspaceCount: workspaces.length,
   });
+  await startLarkLongConnections(reason);
   return true;
 }
 
 export async function stopLarkRuntime(reason: string): Promise<void> {
   if (!larkRuntimeStarted) return;
   larkRuntimeStarted = false;
+  await stopLarkLongConnections(reason);
   tenantTokenCache.clear();
   botOpenIdCache.clear();
   sentMessageThreadMap.clear();