@controlflow-ai/daemon 0.1.1 → 0.1.3

package/src/lark/setup.ts

@@ -1,6 +1,8 @@
 import { createInterface } from 'node:readline';
+import QRCode from 'qrcode';
 import type { LarkCredential } from './credentials.js';
 import { loadLarkCredentials, saveLarkCredentials, upsertCredential } from './credentials.js';
+import { beginLarkAppRegistration, pollLarkAppRegistration, type LarkRegistrationComplete } from './app-registration.js';
 
 export interface CredentialValidationOk {
   ok: true;
@@ -62,6 +64,7 @@ export interface InteractiveSetupOptions {
   listAgents?: () => Promise<LarkSetupAgentOption[]>;
   validateCredentials?: typeof validateLarkCredentials;
   resolveBotInfo?: typeof resolveLarkBotInfo;
+  registerApp?: typeof registerLarkAppFromDeviceFlow;
 }
 
 function clean(value: string | undefined): string | undefined {
@@ -69,6 +72,41 @@ function clean(value: string | undefined): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+export async function registerLarkAppFromDeviceFlow(options: {
+  log: Pick<Console, 'log' | 'warn' | 'error'>;
+  qrCode?: (url: string) => Promise<string>;
+  fetchImpl?: FetchLike;
+}): Promise<LarkRegistrationComplete | null> {
+  const begin = await beginLarkAppRegistration({ fetchImpl: options.fetchImpl, source: 'pal' });
+  options.log.log('Create a Feishu app by scanning this QR code or opening the link:');
+  options.log.log('');
+  const terminalQr = options.qrCode
+    ? await options.qrCode(begin.url)
+    : await QRCode.toString(begin.url, { type: 'terminal', small: true });
+  options.log.log(terminalQr);
+  options.log.log(begin.url);
+  options.log.log('');
+  options.log.log(`Waiting for confirmation. The code expires in about ${Math.max(1, Math.round(begin.expiresIn / 60))} minutes.`);
+
+  let intervalMs = Math.max(1, begin.interval) * 1000;
+  const deadline = Date.now() + begin.expiresIn * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    const result = await pollLarkAppRegistration({ deviceCode: begin.deviceCode, fetchImpl: options.fetchImpl });
+    if (result.status === 'pending') continue;
+    if (result.status === 'slow_down') {
+      intervalMs = Math.max(intervalMs + 5000, result.interval * 1000);
+      options.log.warn(`Feishu asked us to slow polling; retrying every ${Math.round(intervalMs / 1000)}s.`);
+      continue;
+    }
+    if (result.status === 'complete') return result.registration;
+    options.log.warn(`App registration did not complete (${result.status}): ${result.message}`);
+    return null;
+  }
+  options.log.warn('App registration expired before it completed.');
+  return null;
+}
+
 async function chooseAgent(options: InteractiveSetupOptions, ask: (question: string) => Promise<string>): Promise<string | null> {
   if (!options.listAgents) {
     return clean(await ask('Bind to agent key [codex]: ')) ?? 'codex';
@@ -79,7 +117,7 @@ async function chooseAgent(options: InteractiveSetupOptions, ask: (question: str
     agents = await options.listAgents();
   } catch (error) {
     options.log.error(`Could not load agent list: ${error instanceof Error ? error.message : String(error)}`);
-    options.log.error('Set up an agent first, then rerun lark setup.');
+    options.log.error('Set up an agent first, then bind the bot from agent settings.');
     return null;
   }
 
@@ -275,9 +313,37 @@ export async function runInteractiveLarkSetup(options: InteractiveSetupOptions):
     const agent = await chooseAgent(options, ask);
     if (!agent) return null;
     options.log.log('');
-    options.log.log('Paste an existing Feishu app credential. Pal will validate it before writing lark.json.');
-    const appId = clean(await ask('App ID (cli_xxx): '));
-    const appSecret = clean(await ask('App Secret: '));
+    options.log.log('Create a Feishu app by scan/link, or paste an existing credential.');
+    options.log.log('  1. Scan or open link to create app');
+    options.log.log('  2. Paste App ID / App Secret');
+    const method = clean(await ask('Setup method [1]: ')) ?? '1';
+    let appId: string | undefined;
+    let appSecret: string | undefined;
+    let scannedUserOpenId: string | undefined;
+    if (method !== '2') {
+      const registerApp = options.registerApp ?? registerLarkAppFromDeviceFlow;
+      const registration = await registerApp({ log: options.log }).catch((error) => {
+        options.log.warn(`App registration failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+      });
+      if (!registration) {
+        options.log.warn('Falling back to manual App ID / App Secret entry.');
+      } else if (registration.tenantBrand === 'lark') {
+        options.log.error('Lark international tenants are not supported yet; Pal currently expects Feishu (feishu.cn) credentials.');
+        options.log.error('No config was written.');
+        return null;
+      } else {
+        appId = registration.appId;
+        appSecret = registration.appSecret;
+        scannedUserOpenId = registration.userOpenId;
+        options.log.log(`App created: ${appId}`);
+        if (scannedUserOpenId) options.log.log(`Scanner open_id: ${scannedUserOpenId}`);
+      }
+    }
+    if (!appId || !appSecret) {
+      appId = clean(await ask('App ID (cli_xxx): '));
+      appSecret = clean(await ask('App Secret: '));
+    }
     if (!appId || !appSecret) {
       options.log.error('App ID and App Secret are required; no config was written.');
       return null;
@@ -315,8 +381,11 @@ export async function runInteractiveLarkSetup(options: InteractiveSetupOptions):
       agent,
       configPath: options.configPath,
     });
+    if (scannedUserOpenId) {
+      options.log.log(`Scanner open_id ${scannedUserOpenId} was detected; add it under Lark authorized users if this user should operate Pal.`);
+    }
     if (result.replaced) {
-      options.log.warn(`[lark setup] overwrote existing credential for appId=${appId} in ${options.configPath}`);
+      options.log.warn(`[lark] overwrote existing credential for appId=${appId} in ${options.configPath}`);
     }
     options.log.log(formatLarkSetupNextSteps(result));
     return result;

package/src/lark/ws-daemon.ts

@@ -10,13 +10,22 @@ export type LarkEventCallback = (event: {
   storeResult: StoreInboundEventResult;
 }) => void | Promise<void>;
 
+export type LarkWebSocketLifecycleCallback = (event: {
+  appId: string;
+  type: 'ready' | 'reconnecting' | 'reconnected' | 'error';
+  error?: string;
+}) => void;
+
 export interface StartLarkDaemonOptions {
   appId: string;
   appSecret: string;
   db: Database;
   onEvent?: LarkEventCallback;
+  onLifecycle?: LarkWebSocketLifecycleCallback;
   logger?: Partial<Pick<Console, 'info' | 'warn' | 'error'>>;
   loggerLevel?: Lark.LoggerLevel;
+  handshakeTimeoutMs?: number;
+  pingTimeoutSec?: number;
 }
 
 export interface LarkDaemonHandle {
@@ -26,6 +35,44 @@ export interface LarkDaemonHandle {
 }
 
 const SUPPORTED_EVENTS = ['im.message.receive_v1', 'card.action.trigger'] as const;
+const silentLarkLogger = {
+  error() {},
+  warn() {},
+  info() {},
+  debug() {},
+  trace() {},
+};
+
+function nestedString(value: unknown, path: string[]): string | null {
+  let current = value;
+  for (const key of path) {
+    if (!current || typeof current !== 'object') return null;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return typeof current === 'string' && current.length > 0 ? current : null;
+}
+
+export function stableLarkEventId(eventName: string, data: unknown): string | null {
+  const headerId = nestedString(data, ['header', 'event_id'])
+    ?? nestedString(data, ['event_id']);
+  if (headerId) return headerId;
+  const derivedId = nestedString(data, ['message', 'message_id'])
+    ?? nestedString(data, ['message', 'open_message_id'])
+    ?? nestedString(data, ['open_message_id']);
+  if (derivedId) return `${eventName}:${derivedId}`;
+  const operatorId = nestedString(data, ['operator', 'operator_id', 'open_id']);
+  if (operatorId) return `${eventName}:${operatorId}:${nestedString(data, ['token']) ?? ''}`;
+  return null;
+}
+
+export function buildLarkEventRawBody(eventName: string, data: unknown): string {
+  const eventId = stableLarkEventId(eventName, data);
+  return JSON.stringify({
+    schema: '2.0',
+    header: eventId ? { event_id: eventId, event_type: eventName } : { event_type: eventName },
+    event: data,
+  });
+}
 
 /**
  * Start a Lark WSClient that subscribes to im.message.receive_v1 +
@@ -45,7 +92,7 @@ export function startLarkDaemon(options: StartLarkDaemonOptions): LarkDaemonHand
   const handlers: Record<string, (data: unknown) => Promise<unknown>> = {};
   for (const eventName of SUPPORTED_EVENTS) {
     handlers[eventName] = async (data) => {
-      const rawBody = JSON.stringify({ schema: '2.0', header: { event_type: eventName }, event: data });
+      const rawBody = buildLarkEventRawBody(eventName, data);
       try {
         const storeResult = await storeInboundEvent(options.db, { appId: options.appId, rawBody });
         if (storeResult.duplicate) {
@@ -75,6 +122,24 @@ export function startLarkDaemon(options: StartLarkDaemonOptions): LarkDaemonHand
     appId: options.appId,
     appSecret: options.appSecret,
     loggerLevel: options.loggerLevel ?? Lark.LoggerLevel.warn,
+    handshakeTimeoutMs: options.handshakeTimeoutMs ?? 15_000,
+    wsConfig: { pingTimeout: options.pingTimeoutSec ?? 10 },
+    onReady: () => {
+      options.onLifecycle?.({ appId: options.appId, type: 'ready' });
+      log.info?.(`[lark/${options.appId}] WSClient ready`);
+    },
+    onReconnecting: () => {
+      options.onLifecycle?.({ appId: options.appId, type: 'reconnecting' });
+      log.warn?.(`[lark/${options.appId}] WSClient reconnecting`);
+    },
+    onReconnected: () => {
+      options.onLifecycle?.({ appId: options.appId, type: 'reconnected' });
+      log.info?.(`[lark/${options.appId}] WSClient reconnected`);
+    },
+    onError: (err) => {
+      options.onLifecycle?.({ appId: options.appId, type: 'error', error: err.message });
+      log.error?.(`[lark/${options.appId}] WSClient error: ${err.message}`);
+    },
   });
 
   wsClient.start({ eventDispatcher });
@@ -103,35 +168,96 @@ export function createLarkApiClient(appId: string, appSecret: string): Lark.Clie
   return new Lark.Client({
     appId,
     appSecret,
-    loggerLevel: Lark.LoggerLevel.warn,
+    loggerLevel: Lark.LoggerLevel.fatal,
+    logger: silentLarkLogger,
   });
 }
 
-export interface SendTextMessageInput {
+export type LarkReceiveIdType = 'chat_id' | 'open_id' | 'union_id' | 'email' | 'user_id';
+
+export interface LarkMentionTarget {
+  openId: string;
+  displayName?: string | null;
+}
+
+interface SendMessageBaseInput {
   client: Lark.Client;
-  receiveIdType: 'chat_id' | 'open_id' | 'union_id' | 'email' | 'user_id';
+  receiveIdType: LarkReceiveIdType;
   receiveId: string;
   text: string;
+  mention?: LarkMentionTarget | null;
 }
 
+export interface SendTextMessageInput extends SendMessageBaseInput {}
+
+export interface SendCardMessageInput extends SendMessageBaseInput {}
+
 export interface SendTextMessageResult {
   messageId?: string;
   raw: unknown;
 }
 
-export async function sendTextMessage(input: SendTextMessageInput): Promise<SendTextMessageResult> {
+export interface LarkMessageCreatePayload {
+  receive_id: string;
+  msg_type: 'text' | 'interactive';
+  content: string;
+}
+
+function escapeLarkText(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function larkMentionSuffix(mention: LarkMentionTarget | null | undefined, tag: 'text' | 'card'): string {
+  if (!mention?.openId) return '';
+  const idAttribute = tag === 'text' ? 'user_id' : 'id';
+  return `\n\n<at ${idAttribute}="${mention.openId}">${escapeLarkText(mention.displayName ?? '')}</at>`;
+}
+
+function larkMessageBody(input: Pick<SendMessageBaseInput, 'text' | 'mention'>, tag: 'text' | 'card'): string {
+  return `${input.text}${larkMentionSuffix(input.mention, tag)}`;
+}
+
+export function buildLarkTextMessagePayload(input: Pick<SendTextMessageInput, 'receiveId' | 'text' | 'mention'>): LarkMessageCreatePayload {
+  return {
+    receive_id: input.receiveId,
+    msg_type: 'text',
+    content: JSON.stringify({ text: larkMessageBody(input, 'text') }),
+  };
+}
+
+export function buildLarkMentionCardPayload(input: Pick<SendCardMessageInput, 'receiveId' | 'text' | 'mention'>): LarkMessageCreatePayload {
+  return {
+    receive_id: input.receiveId,
+    msg_type: 'interactive',
+    content: JSON.stringify({
+      config: { wide_screen_mode: true },
+      elements: [
+        {
+          tag: 'markdown',
+          content: larkMessageBody(input, 'card'),
+        },
+      ],
+    }),
+  };
+}
+
+async function createLarkMessage(input: SendMessageBaseInput, payload: LarkMessageCreatePayload): Promise<SendTextMessageResult> {
   const response = await input.client.im.message.create({
     params: { receive_id_type: input.receiveIdType },
-    data: {
-      receive_id: input.receiveId,
-      msg_type: 'text',
-      content: JSON.stringify({ text: input.text }),
-    },
+    data: payload,
   });
   const messageId = (response?.data as { message_id?: string } | undefined)?.message_id;
   return { messageId, raw: response };
 }
 
+export async function sendTextMessage(input: SendTextMessageInput): Promise<SendTextMessageResult> {
+  return createLarkMessage(input, buildLarkTextMessagePayload(input));
+}
+
+export async function sendCardMessage(input: SendCardMessageInput): Promise<SendTextMessageResult> {
+  return createLarkMessage(input, buildLarkMentionCardPayload(input));
+}
+
 export interface AddMessageReactionInput {
   client: Lark.Client;
   messageId: string;