@controlflow-ai/daemon 0.1.0

package/src/lark/setup.ts

@@ -0,0 +1,326 @@
+import { createInterface } from 'node:readline';
+import type { LarkCredential } from './credentials.js';
+import { loadLarkCredentials, saveLarkCredentials, upsertCredential } from './credentials.js';
+
+export interface CredentialValidationOk {
+  ok: true;
+  tokenExpiresIn: number;
+}
+
+export interface CredentialValidationFail {
+  ok: false;
+  error: 'invalid_credentials' | 'network' | 'unknown';
+  message: string;
+}
+
+export type CredentialValidationResult = CredentialValidationOk | CredentialValidationFail;
+
+export interface LarkBotInfoOk {
+  ok: true;
+  openId: string;
+  appName?: string;
+}
+
+export interface LarkBotInfoFail {
+  ok: false;
+  error: 'invalid_credentials' | 'network' | 'unknown';
+  message: string;
+}
+
+export type LarkBotInfoResult = LarkBotInfoOk | LarkBotInfoFail;
+
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export interface PersistLarkCredentialInput {
+  appId: string;
+  appSecret: string;
+  label?: string;
+  agent?: string;
+  botOpenId?: string;
+  configPath: string;
+}
+
+export interface PersistLarkCredentialResult {
+  path: string;
+  appId: string;
+  agent: string | null;
+  botOpenId: string | null;
+  replaced: boolean;
+  bots: number;
+}
+
+export interface LarkSetupAgentOption {
+  agent_key: string;
+  display_name: string;
+  runtime?: string | null;
+}
+
+export interface InteractiveSetupOptions {
+  configPath: string;
+  log: Pick<Console, 'log' | 'warn' | 'error'>;
+  ask?: (question: string) => Promise<string>;
+  listAgents?: () => Promise<LarkSetupAgentOption[]>;
+  validateCredentials?: typeof validateLarkCredentials;
+  resolveBotInfo?: typeof resolveLarkBotInfo;
+}
+
+function clean(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+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';
+  }
+
+  let agents: LarkSetupAgentOption[];
+  try {
+    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.');
+    return null;
+  }
+
+  if (agents.length === 0) {
+    options.log.error('No agents found. Set up an agent first with "bun run console -- agents onboard".');
+    return null;
+  }
+
+  options.log.log('Choose the Pal agent this Feishu bot should deliver to:');
+  agents.forEach((agent, index) => {
+    options.log.log(`  ${index + 1}. ${agent.display_name} (${agent.agent_key}) runtime=${agent.runtime ?? '-'}`);
+  });
+
+  while (true) {
+    const answer = clean(await ask(agents.length === 1 ? 'Agent [1]: ' : 'Agent: ')) ?? (agents.length === 1 ? '1' : undefined);
+    const selected = answer ? agents[Number(answer) - 1] ?? agents.find((agent) => agent.agent_key === answer) : undefined;
+    if (selected) return selected.agent_key;
+    options.log.error('Choose a listed number or agent key.');
+  }
+}
+
+
+export async function validateLarkCredentials(
+  appId: string,
+  appSecret: string,
+  options: { budgetMs?: number; fetchImpl?: FetchLike } = {},
+): Promise<CredentialValidationResult> {
+  const budgetMs = options.budgetMs ?? 10_000;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), budgetMs);
+  let response: Response;
+  let body: { code?: unknown; msg?: unknown; expire?: unknown; tenant_access_token?: unknown };
+  try {
+    response = await fetchImpl('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+      signal: controller.signal,
+    });
+    body = await response.json();
+  } catch (err) {
+    clearTimeout(timer);
+    const aborted = controller.signal.aborted || (err instanceof Error && err.name === 'AbortError');
+    return {
+      ok: false,
+      error: 'network',
+      message: aborted ? `request timed out after ${budgetMs}ms` : `network error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  clearTimeout(timer);
+
+  if (body.code === 0 && typeof body.tenant_access_token === 'string') {
+    return { ok: true, tokenExpiresIn: typeof body.expire === 'number' ? body.expire : 7200 };
+  }
+  if (body.code === 10003 || body.code === 10012 || body.code === 99991663) {
+    return { ok: false, error: 'invalid_credentials', message: `invalid credentials (code=${body.code})` };
+  }
+  return { ok: false, error: 'unknown', message: `code=${String(body.code ?? '?')} msg=${String(body.msg ?? '')}` };
+}
+
+async function fetchTenantAccessToken(
+  appId: string,
+  appSecret: string,
+  options: { budgetMs?: number; fetchImpl?: FetchLike } = {},
+): Promise<{ ok: true; token: string; expire: number } | CredentialValidationFail> {
+  const budgetMs = options.budgetMs ?? 10_000;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), budgetMs);
+  let response: Response;
+  let body: { code?: unknown; msg?: unknown; expire?: unknown; tenant_access_token?: unknown };
+  try {
+    response = await fetchImpl('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+      signal: controller.signal,
+    });
+    body = await response.json();
+  } catch (err) {
+    clearTimeout(timer);
+    const aborted = controller.signal.aborted || (err instanceof Error && err.name === 'AbortError');
+    return {
+      ok: false,
+      error: 'network',
+      message: aborted ? `request timed out after ${budgetMs}ms` : `network error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  clearTimeout(timer);
+
+  if (body.code === 0 && typeof body.tenant_access_token === 'string') {
+    return { ok: true, token: body.tenant_access_token, expire: typeof body.expire === 'number' ? body.expire : 7200 };
+  }
+  if (body.code === 10003 || body.code === 10012 || body.code === 99991663) {
+    return { ok: false, error: 'invalid_credentials', message: `invalid credentials (code=${body.code})` };
+  }
+  return { ok: false, error: 'unknown', message: `code=${String(body.code ?? '?')} msg=${String(body.msg ?? '')}` };
+}
+
+export async function resolveLarkBotInfo(
+  appId: string,
+  appSecret: string,
+  options: { budgetMs?: number; fetchImpl?: FetchLike } = {},
+): Promise<LarkBotInfoResult> {
+  const budgetMs = options.budgetMs ?? 10_000;
+  const token = await fetchTenantAccessToken(appId, appSecret, options);
+  if (!token.ok) return token;
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), budgetMs);
+  try {
+    const response = await fetchImpl('https://open.feishu.cn/open-apis/bot/v3/info', {
+      method: 'GET',
+      headers: { authorization: `Bearer ${token.token}` },
+      signal: controller.signal,
+    });
+    const body = await response.json() as { code?: unknown; msg?: unknown; bot?: { open_id?: unknown; app_name?: unknown } };
+    clearTimeout(timer);
+    if (body.code === 0 && typeof body.bot?.open_id === 'string' && body.bot.open_id.trim()) {
+      return {
+        ok: true,
+        openId: body.bot.open_id,
+        appName: typeof body.bot.app_name === 'string' ? body.bot.app_name : undefined,
+      };
+    }
+    return { ok: false, error: 'unknown', message: `code=${String(body.code ?? '?')} msg=${String(body.msg ?? '')}` };
+  } catch (err) {
+    clearTimeout(timer);
+    const aborted = controller.signal.aborted || (err instanceof Error && err.name === 'AbortError');
+    return {
+      ok: false,
+      error: 'network',
+      message: aborted ? `request timed out after ${budgetMs}ms` : `network error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+export function persistLarkCredential(input: PersistLarkCredentialInput): PersistLarkCredentialResult {
+  const credential: LarkCredential = {
+    appId: input.appId,
+    appSecret: input.appSecret,
+  };
+  if (clean(input.label)) credential.label = clean(input.label);
+  if (clean(input.agent)) credential.agent = clean(input.agent);
+  if (clean(input.botOpenId)) credential.botOpenId = clean(input.botOpenId);
+
+  const store = loadLarkCredentials(input.configPath);
+  const { store: next, replaced } = upsertCredential(store, credential);
+  saveLarkCredentials(next, input.configPath);
+  return {
+    path: input.configPath,
+    appId: input.appId,
+    agent: credential.agent ?? null,
+    botOpenId: credential.botOpenId ?? null,
+    replaced,
+    bots: next.bots.length,
+  };
+}
+
+export function formatLarkSetupNextSteps(result: PersistLarkCredentialResult): string {
+  return [
+    '',
+    'Lark bot saved.',
+    `  Config: ${result.path}`,
+    `  App ID: ${result.appId}`,
+    `  Agent binding: ${result.agent ?? '(none)'}`,
+    `  Bot open_id: ${result.botOpenId ?? '(not set)'}`,
+    '',
+    'Next steps:',
+    '  1. In Feishu Open Platform, enable bot capability and event subscriptions:',
+    '     - im.message.receive_v1',
+    '     - card.action.trigger',
+    '     Use long connection / WebSocket event delivery.',
+    '  2. Grant the message, chat, contact, and reaction scopes required by Pal.',
+    '  3. Confirm the bound agent exists, has runtime=codex, and is assigned to one computer.',
+    '  4. Reload Lark integration or keep the default setup reload enabled.',
+    '  5. Verify with: bun run console -- lark list && bun run console -- lark events --limit 20',
+    '',
+  ].join('\n');
+}
+
+export async function runInteractiveLarkSetup(options: InteractiveSetupOptions): Promise<PersistLarkCredentialResult | null> {
+  const closeable = options.ask
+    ? null
+    : createInterface({ input: process.stdin, output: process.stdout });
+  const ask = options.ask ?? ((question: string) => new Promise<string>((resolve) => closeable!.question(question, resolve)));
+  try {
+    options.log.log('Pal Lark setup');
+    options.log.log(`Config path: ${options.configPath}`);
+    options.log.log('');
+    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: '));
+    if (!appId || !appSecret) {
+      options.log.error('App ID and App Secret are required; no config was written.');
+      return null;
+    }
+    const label = clean(await ask('Bot label / display name [optional]: '));
+    let botOpenId: string | undefined;
+
+    options.log.log('');
+    options.log.log('Validating credentials...');
+    const validate = options.validateCredentials ?? validateLarkCredentials;
+    const validation = await validate(appId, appSecret);
+    if (!validation.ok) {
+      options.log.error(`Credential validation failed (${validation.error}): ${validation.message}`);
+      options.log.error('No config was written.');
+      return null;
+    }
+    options.log.log('Credentials validated.');
+    options.log.log('Resolving bot open_id...');
+    const resolveBotInfo = options.resolveBotInfo ?? resolveLarkBotInfo;
+    const botInfo = await resolveBotInfo(appId, appSecret);
+    if (botInfo.ok) {
+      botOpenId = botInfo.openId;
+      options.log.log(`Bot open_id resolved${botInfo.appName ? ` for ${botInfo.appName}` : ''}.`);
+    } else {
+      options.log.error(`Bot open_id lookup failed (${botInfo.error}): ${botInfo.message}`);
+      options.log.error('No config was written.');
+      return null;
+    }
+
+    const result = persistLarkCredential({
+      appId,
+      appSecret,
+      label,
+      botOpenId,
+      agent,
+      configPath: options.configPath,
+    });
+    if (result.replaced) {
+      options.log.warn(`[lark setup] overwrote existing credential for appId=${appId} in ${options.configPath}`);
+    }
+    options.log.log(formatLarkSetupNextSteps(result));
+    return result;
+  } finally {
+    closeable?.close();
+  }
+}

package/src/lark/ws-daemon.ts

@@ -0,0 +1,224 @@
+import * as Lark from '@larksuiteoapi/node-sdk';
+import type { Database } from 'bun:sqlite';
+import { storeInboundEvent, type StoreInboundEventResult } from './inbound-events.js';
+
+export type LarkEventCallback = (event: {
+  appId: string;
+  envelope: 'im.message.receive_v1' | 'card.action.trigger' | string;
+  data: unknown;
+  rawBody: string;
+  storeResult: StoreInboundEventResult;
+}) => void | Promise<void>;
+
+export interface StartLarkDaemonOptions {
+  appId: string;
+  appSecret: string;
+  db: Database;
+  onEvent?: LarkEventCallback;
+  logger?: Partial<Pick<Console, 'info' | 'warn' | 'error'>>;
+  loggerLevel?: Lark.LoggerLevel;
+}
+
+export interface LarkDaemonHandle {
+  appId: string;
+  wsClient: Lark.WSClient;
+  stop(): void;
+}
+
+const SUPPORTED_EVENTS = ['im.message.receive_v1', 'card.action.trigger'] as const;
+
+/**
+ * Start a Lark WSClient that subscribes to im.message.receive_v1 +
+ * card.action.trigger and persists every event into channel_inbound_raw_events
+ * with dedupe. Callers can pass an onEvent callback for downstream processing
+ * (e.g. routing to internal LockClient chats).
+ *
+ * Returns a handle whose stop() closes the WSClient.
+ */
+export function startLarkDaemon(options: StartLarkDaemonOptions): LarkDaemonHandle {
+  const log = {
+    info: options.logger?.info ?? console.log,
+    warn: options.logger?.warn ?? console.warn,
+    error: options.logger?.error ?? console.error,
+  };
+
+  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 });
+      try {
+        const storeResult = await storeInboundEvent(options.db, { appId: options.appId, rawBody });
+        if (storeResult.duplicate) {
+          log.info?.(`[lark/${options.appId}] dup ${storeResult.event_id} (${eventName})`);
+          return undefined;
+        }
+        if (options.onEvent) {
+          await options.onEvent({
+            appId: options.appId,
+            envelope: eventName,
+            data,
+            rawBody,
+            storeResult,
+          });
+        }
+        return undefined;
+      } catch (err) {
+        log.error?.(`[lark/${options.appId}] handler error on ${eventName}:`, err);
+        return undefined;
+      }
+    };
+  }
+
+  const eventDispatcher = new Lark.EventDispatcher({}).register(handlers);
+
+  const wsClient = new Lark.WSClient({
+    appId: options.appId,
+    appSecret: options.appSecret,
+    loggerLevel: options.loggerLevel ?? Lark.LoggerLevel.warn,
+  });
+
+  wsClient.start({ eventDispatcher });
+  log.info?.(`[lark/${options.appId}] WSClient started`);
+
+  return {
+    appId: options.appId,
+    wsClient,
+    stop(): void {
+      try {
+        const anyClient = wsClient as unknown as { stop?: () => void; close?: () => void };
+        if (typeof anyClient.stop === 'function') {
+          anyClient.stop();
+        } else if (typeof anyClient.close === 'function') {
+          anyClient.close();
+        }
+        log.info?.(`[lark/${options.appId}] WSClient stopped`);
+      } catch (err) {
+        log.warn?.(`[lark/${options.appId}] stop error:`, err);
+      }
+    },
+  };
+}
+
+export function createLarkApiClient(appId: string, appSecret: string): Lark.Client {
+  return new Lark.Client({
+    appId,
+    appSecret,
+    loggerLevel: Lark.LoggerLevel.warn,
+  });
+}
+
+export interface SendTextMessageInput {
+  client: Lark.Client;
+  receiveIdType: 'chat_id' | 'open_id' | 'union_id' | 'email' | 'user_id';
+  receiveId: string;
+  text: string;
+}
+
+export interface SendTextMessageResult {
+  messageId?: string;
+  raw: unknown;
+}
+
+export async function sendTextMessage(input: SendTextMessageInput): 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 }),
+    },
+  });
+  const messageId = (response?.data as { message_id?: string } | undefined)?.message_id;
+  return { messageId, raw: response };
+}
+
+export interface AddMessageReactionInput {
+  client: Lark.Client;
+  messageId: string;
+  emojiType: string;
+}
+
+export interface AddMessageReactionResult {
+  reactionId?: string;
+  raw: unknown;
+}
+
+export async function addMessageReaction(input: AddMessageReactionInput): Promise<AddMessageReactionResult> {
+  const response = await input.client.im.messageReaction.create({
+    path: { message_id: input.messageId },
+    data: {
+      reaction_type: { emoji_type: input.emojiType },
+    },
+  });
+  const reactionId = (response?.data as { reaction_id?: string } | undefined)?.reaction_id;
+  return { reactionId, raw: response };
+}
+
+export interface GetChatInfoInput {
+  client: Lark.Client;
+  chatId: string;
+}
+
+export interface GetChatInfoResult {
+  name?: string;
+  chatMode?: string;
+  raw: unknown;
+}
+
+export async function getChatInfo(input: GetChatInfoInput): Promise<GetChatInfoResult> {
+  const response = await input.client.im.chat.get({
+    path: { chat_id: input.chatId },
+  });
+  const data = response?.data as { name?: string; chat_mode?: string } | undefined;
+  return { name: data?.name, chatMode: data?.chat_mode, raw: response };
+}
+
+export interface GetChatMembersInput {
+  client: Lark.Client;
+  chatId: string;
+  pageSize?: number;
+}
+
+export interface LarkChatMember {
+  memberId: string;
+  memberIdType?: string;
+  name?: string;
+}
+
+export interface GetChatMembersResult {
+  members: LarkChatMember[];
+  raw: unknown[];
+}
+
+export async function getChatMembers(input: GetChatMembersInput): Promise<GetChatMembersResult> {
+  const members: LarkChatMember[] = [];
+  const raw: unknown[] = [];
+  let pageToken: string | undefined;
+  do {
+    const response = await input.client.im.chatMembers.get({
+      path: { chat_id: input.chatId },
+      params: {
+        member_id_type: 'open_id',
+        page_size: input.pageSize ?? 100,
+        page_token: pageToken,
+      },
+    });
+    raw.push(response);
+    const data = response?.data as {
+      items?: Array<{ member_id?: string; member_id_type?: string; name?: string }>;
+      page_token?: string;
+      has_more?: boolean;
+    } | undefined;
+    for (const item of data?.items ?? []) {
+      const memberId = item.member_id?.trim();
+      if (!memberId) continue;
+      members.push({
+        memberId,
+        memberIdType: item.member_id_type,
+        name: item.name,
+      });
+    }
+    pageToken = data?.has_more ? data.page_token : undefined;
+  } while (pageToken);
+  return { members, raw };
+}

package/src/lark-fixture-diagnostics.ts

@@ -0,0 +1,56 @@
+import type { ApplyFixtureResult, NormalizedLarkFixtureEvent } from './lark-fixture.js';
+
+export type FixtureDiagnosticState = 'observed' | 'missing' | 'ignored' | 'rejected' | 'unmapped';
+
+export interface FixtureDiagnostic {
+  fixture_id: string;
+  scope: NormalizedLarkFixtureEvent['scope'];
+  conversation_key_state: FixtureDiagnosticState;
+  audit_status: NormalizedLarkFixtureEvent['audit_status'];
+  normalized_recipient_hint_state: FixtureDiagnosticState;
+  rejection_reason: string | null;
+  transcript_state: FixtureDiagnosticState;
+  mapping_state: FixtureDiagnosticState;
+}
+
+export interface FixtureDiagnosticsSummary {
+  total: number;
+  by_audit_status: Record<string, number>;
+  by_scope: Record<string, number>;
+  diagnostics: FixtureDiagnostic[];
+}
+
+export function buildFixtureDiagnostics(results: ApplyFixtureResult[]): FixtureDiagnosticsSummary {
+  const diagnostics = results
+    .map(toDiagnostic)
+    .sort((left, right) => left.fixture_id.localeCompare(right.fixture_id));
+
+  return {
+    total: diagnostics.length,
+    by_audit_status: countBy(diagnostics, (item) => item.audit_status),
+    by_scope: countBy(diagnostics, (item) => item.scope),
+    diagnostics,
+  };
+}
+
+function toDiagnostic(result: ApplyFixtureResult): FixtureDiagnostic {
+  return {
+    fixture_id: result.normalized.fixture_id,
+    scope: result.normalized.scope,
+    conversation_key_state: result.normalized.conversation_key ? 'observed' : 'missing',
+    audit_status: result.normalized.audit_status,
+    normalized_recipient_hint_state: result.normalized.delivery_recipient ? 'observed' : 'missing',
+    rejection_reason: result.normalized.rejection_reason,
+    transcript_state: result.transcriptId ? 'observed' : result.normalized.audit_status === 'mapped' ? 'unmapped' : result.normalized.audit_status,
+    mapping_state: result.mappingId ? 'observed' : 'missing',
+  };
+}
+
+function countBy<T>(items: T[], key: (item: T) => string): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const item of items) {
+    const value = key(item);
+    counts[value] = (counts[value] ?? 0) + 1;
+  }
+  return counts;
+}