@controlflow-ai/daemon 0.1.0

package/src/lark/cli.ts

@@ -0,0 +1,549 @@
+import { readFileSync } from 'node:fs';
+import { defaultDbPath, defaultServerUrl } from '../config.js';
+import { MessageStore } from '../db.js';
+import {
+  boundAgents,
+  defaultLarkConfigPath,
+  findCredential,
+  loadLarkCredentials,
+} from './credentials.js';
+import { countInboundEvents, listRecentInboundEvents } from './inbound-events.js';
+import { extractMentionOpenIds, ingestLarkMessage, type LarkMessageEnvelope } from './event-router.js';
+import { ChatDispatcher, chatKeyOf, parseReceivePolicy, PeriodicQueue, shouldAcceptForAgent, type DispatchInput, type ReceivePolicy } from './dispatcher.js';
+import { parseRuntimeSpec } from './agent-runtime.js';
+import {
+  formatLarkSetupNextSteps,
+  persistLarkCredential,
+  resolveLarkBotInfo,
+  runInteractiveLarkSetup,
+} from './setup.js';
+import { createLarkApiClient, sendTextMessage, startLarkDaemon } from './ws-daemon.js';
+
+export interface LarkCliArgs {
+  command: string;
+  values: string[];
+  flags: Record<string, unknown>;
+}
+
+interface RunOptions {
+  argv: LarkCliArgs;
+  log?: Partial<Pick<Console, 'log' | 'warn' | 'error'>>;
+  setupAsk?: (question: string) => Promise<string>;
+}
+
+function printJson(value: unknown, log: NonNullable<RunOptions['log']>): void {
+  (log.log ?? console.log)(JSON.stringify(value, null, 2));
+}
+
+function flagString(flags: Record<string, unknown>, key: string): string | undefined {
+  const v = flags[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+function flagBool(flags: Record<string, unknown>, key: string): boolean {
+  return flags[key] === true;
+}
+
+async function postJson(url: string, body: unknown): Promise<{ ok: boolean; status: number; text: string }> {
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return { ok: response.ok, status: response.status, text: await response.text() };
+  } catch (error) {
+    return { ok: false, status: 0, text: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+async function listAgentsForSetup(serverUrl: string): Promise<Array<{ agent_key: string; display_name: string; runtime?: string | null }>> {
+  const response = await fetch(`${serverUrl.replace(/\/$/, '')}/api/agents`);
+  const payload = await response.json() as { ok?: boolean; data?: { agents?: Array<{ agent_key?: unknown; display_name?: unknown; runtime?: unknown }> }; message?: string };
+  if (!response.ok || payload.ok === false) {
+    throw new Error(payload.message ?? `agent list failed: ${response.status}`);
+  }
+  return (payload.data?.agents ?? [])
+    .filter((agent) => typeof agent.agent_key === 'string' && typeof agent.display_name === 'string')
+    .map((agent) => ({
+      agent_key: String(agent.agent_key),
+      display_name: String(agent.display_name),
+      runtime: agent.runtime === null || typeof agent.runtime === 'string' ? agent.runtime : undefined,
+    }));
+}
+
+async function onboardAgentForLark(flags: Record<string, unknown>, log: NonNullable<RunOptions['log']>, agent: string | undefined): Promise<boolean> {
+  if (!flagBool(flags, 'create-agent')) return true;
+  if (!agent) {
+    (log.error ?? console.error)('lark setup --create-agent requires --agent');
+    return false;
+  }
+  const serverUrl = flagString(flags, 'server') ?? defaultServerUrl();
+  const displayName = flagString(flags, 'agent-name') ?? agent;
+  const runtime = flagString(flags, 'runtime') ?? 'codex';
+  const computerId = flagString(flags, 'computer-id');
+  const result = await postJson(`${serverUrl.replace(/\/$/, '')}/api/agents/onboard`, {
+    agent_key: agent,
+    display_name: displayName,
+    runtime,
+    computer_id: computerId,
+  });
+  if (!result.ok) {
+    (log.error ?? console.error)(`agent onboard failed (${result.status || 'network'}): ${result.text}`);
+    return false;
+  }
+  (log.log ?? console.log)(`[lark setup] agent onboarded: ${agent}`);
+  return true;
+}
+
+async function reloadLarkIntegration(flags: Record<string, unknown>, log: NonNullable<RunOptions['log']>): Promise<void> {
+  if (flagBool(flags, 'no-reload')) return;
+  const serverUrl = flagString(flags, 'server') ?? defaultServerUrl();
+  const result = await postJson(`${serverUrl.replace(/\/$/, '')}/api/lark/reload`, {});
+  if (result.ok) {
+    (log.log ?? console.log)('[lark setup] server lark integration reloaded');
+  } else {
+    (log.warn ?? console.warn)(`[lark setup] saved config, but server reload failed (${result.status || 'network'}): ${result.text}`);
+  }
+}
+
+export async function runLarkCli(options: RunOptions): Promise<number> {
+  const { argv } = options;
+  const log = options.log ?? {};
+  const sub = argv.values[0];
+
+  if (!sub || sub === 'help' || flagBool(argv.flags, 'help')) {
+    printLarkUsage(log);
+    return 0;
+  }
+
+  if (sub === 'setup') {
+    const appId = flagString(argv.flags, 'app-id');
+    const appSecret = flagString(argv.flags, 'app-secret');
+    const label = flagString(argv.flags, 'label');
+    const agent = flagString(argv.flags, 'agent');
+    const path = flagString(argv.flags, 'config') ?? defaultLarkConfigPath();
+    if ('agents' in argv.flags) {
+      (log.error ?? console.error)('lark setup no longer supports --agents; bind one bot to one agent with --agent');
+      return 2;
+    }
+    if (!appId && !appSecret) {
+      const result = await runInteractiveLarkSetup({
+        configPath: path,
+        log: {
+          log: log.log ?? console.log,
+          warn: log.warn ?? console.warn,
+          error: log.error ?? console.error,
+        },
+        ask: options.setupAsk,
+        listAgents: () => listAgentsForSetup(flagString(argv.flags, 'server') ?? defaultServerUrl()),
+      });
+      if (result) await reloadLarkIntegration(argv.flags, log);
+      return result ? 0 : 2;
+    }
+    if (!appId || !appSecret) {
+      (log.error ?? console.error)('lark setup requires --app-id and --app-secret');
+      return 2;
+    }
+    if (!(await onboardAgentForLark(argv.flags, log, agent))) return 2;
+    const botInfo = await resolveLarkBotInfo(appId, appSecret);
+    if (!botInfo.ok) {
+      (log.error ?? console.error)(`lark setup could not resolve bot open_id (${botInfo.error}): ${botInfo.message}`);
+      return 2;
+    }
+    const result = persistLarkCredential({
+      appId,
+      appSecret,
+      label,
+      agent,
+      botOpenId: botInfo.openId,
+      configPath: path,
+    });
+    if (result.replaced) {
+      (log.warn ?? console.warn)(`[lark setup] overwrote existing credential for appId=${appId} in ${path}`);
+    }
+    if (flagBool(argv.flags, 'next-steps')) {
+      (log.log ?? console.log)(formatLarkSetupNextSteps(result));
+      await reloadLarkIntegration(argv.flags, log);
+      return 0;
+    }
+    printJson(result, { log: log.log });
+    await reloadLarkIntegration(argv.flags, log);
+    return 0;
+  }
+
+  if (sub === 'list') {
+    // Listing config file contents (acceptor-locked: no remote list, only read local file)
+    const path = flagString(argv.flags, 'config') ?? defaultLarkConfigPath();
+    const store = loadLarkCredentials(path);
+    const safe = store.bots.map((b) => ({ appId: b.appId, label: b.label, agent: b.agent ?? null, boundAgents: boundAgents(b), botOpenId: b.botOpenId ?? null, hasSecret: Boolean(b.appSecret) }));
+    printJson({ path, bots: safe }, { log: log.log });
+    return 0;
+  }
+
+  if (sub === 'events') {
+    const path = flagString(argv.flags, 'db') ?? defaultDbPath();
+    const limit = Number(flagString(argv.flags, 'limit') ?? '20');
+    const store = new MessageStore(path);
+    try {
+      const total = countInboundEvents(store.db);
+      const rows = listRecentInboundEvents(store.db, Number.isFinite(limit) ? limit : 20);
+      printJson({
+        path,
+        total,
+        rows: rows.map((r) => ({
+          id: r.id,
+          received_at: r.received_at,
+          app_id: r.app_id,
+          event_type: r.event_type,
+          event_id: r.event_id,
+          parse_ok: r.parse_ok,
+          bytes: r.raw_body_bytes?.byteLength ?? 0,
+        })),
+      }, { log: log.log });
+    } finally {
+      store.close();
+    }
+    return 0;
+  }
+
+  if (sub === 'daemon') {
+    return runDaemon(argv, log);
+  }
+
+  if (sub === 'send') {
+    return runSend(argv, log);
+  }
+
+  printLarkUsage(log);
+  return 2;
+}
+
+function printLarkUsage(log: NonNullable<RunOptions['log']>): void {
+  (log.log ?? console.log)(`pal lark <subcommand> [flags]
+
+Subcommands:
+  setup [--app-id <id> --app-secret <secret>] [--label <name>] [--agent <agent-key>] [--config <path>] [--next-steps]
+        [--create-agent --agent-name <name> --runtime codex --computer-id <machine>] [--server <url>] [--no-reload]
+      Persist a (appId, appSecret) credential pair to ~/.pal/lark.json (0600).
+      With no app-id/app-secret flags, starts an interactive setup wizard that
+      validates credentials before writing the config.
+      Overwrites if appId already present and logs a warning.
+      Setup resolves the bot open_id through Feishu's bot info API before
+      writing config. --agent binds this bot to a logical agent key. --create-agent creates or
+      updates that agent through the Pal server before writing lark.json.
+      By default setup asks the running server to reload Lark integration.
+
+  list [--config <path>]
+      List configured bots (secrets redacted).
+
+  daemon [--app-id <id> | --all] [--config <path>] [--db <path>] [--agent <runtime-spec>] [--no-reply]
+         [--policy every|mention|off]
+      Start a WSClient and stream events into channel_inbound_raw_events with dedupe.
+      When --agent is set (e.g. echo, echo:bot, shell:'bun -e ...'), every fresh
+      lock message triggers the agent; the agent's reply is sent back via Lark
+      unless --no-reply is set.
+      If --agent is omitted and the bot config has an "agent" field, that value is used.
+      --policy controls when the agent runs (default: every).
+        - every:    agent runs for every fresh message in any chat
+        - mention:  only when the bot's own open_id appears in @mentions
+        - periodic: messages buffer per-chat; flush on --periodic-interval-ms ticks
+        - off:      ingest + store, but never dispatch to agent
+      --periodic-interval-ms sets the pull interval for policy=periodic (default 30000 = 30s).
+      Send SIGUSR1 to restart-all (re-deliver in-flight + pending), SIGUSR2 to kill-all (drop),
+      SIGHUP to flush all periodic buffers immediately.
+
+  events [--db <path>] [--limit 20]
+      Show recently stored raw events.
+
+  send --app-id <id> --to <receive_id> [--to-type chat_id|open_id|union_id|email|user_id] <text>
+      Send a text message via the bot identified by app-id.
+
+Environment:
+  PAL_HOME             home dir (default ~/.pal)
+  PAL_LARK_CONFIG      override lark.json path
+  PAL_DB               override sqlite db path
+`);
+}
+
+async function runDaemon(argv: LarkCliArgs, log: NonNullable<RunOptions['log']>): Promise<number> {
+  const configPath = flagString(argv.flags, 'config') ?? defaultLarkConfigPath();
+  const dbPath = flagString(argv.flags, 'db') ?? defaultDbPath();
+  const all = flagBool(argv.flags, 'all');
+  const onlyAppId = flagString(argv.flags, 'app-id');
+  let agentSpec = flagString(argv.flags, 'agent');
+  const replyToLark = !flagBool(argv.flags, 'no-reply');
+  const policy: ReceivePolicy = parseReceivePolicy(flagString(argv.flags, 'policy'), 'every');
+  const periodicIntervalMs = Number(flagString(argv.flags, 'periodic-interval-ms') ?? '30000');
+  if (policy === 'periodic' && (!Number.isFinite(periodicIntervalMs) || periodicIntervalMs <= 0)) {
+    (log.error ?? console.error)('--periodic-interval-ms must be a positive number');
+    return 2;
+  }
+  const store = loadLarkCredentials(configPath);
+  if (store.bots.length === 0) {
+    (log.error ?? console.error)(`No bots configured in ${configPath}. Run pal lark setup first.`);
+    return 2;
+  }
+  let targets = store.bots;
+  if (!all) {
+    if (!onlyAppId) {
+      if (store.bots.length === 1) {
+        targets = [store.bots[0]];
+      } else {
+        (log.error ?? console.error)('Multiple bots configured; pass --app-id <id> or --all.');
+        return 2;
+      }
+    } else {
+      const single = findCredential(store, onlyAppId);
+      if (!single) {
+        (log.error ?? console.error)(`appId ${onlyAppId} not found in ${configPath}.`);
+        return 2;
+      }
+      targets = [single];
+    }
+  }
+
+  // If no --agent flag, fall back to the agent bound in lark.json for the target bot(s).
+  if (!agentSpec && targets.length > 0) {
+    const boundAgents = targets.map((b) => b.agent).filter((a): a is string => Boolean(a));
+    const unique = Array.from(new Set(boundAgents));
+    if (unique.length === 1) {
+      agentSpec = unique[0];
+      (log.log ?? console.log)(`[lark] using bound agent from config: ${agentSpec}`);
+    } else if (unique.length > 1) {
+      (log.warn ?? console.warn)(`[lark] multiple bots have different bound agents (${unique.join(', ')}); pass --agent explicitly`);
+    } else {
+      (log.warn ?? console.warn)(`[lark] no agent bound in config; pass --agent explicitly`);
+    }
+  }
+
+  const msgStore = new MessageStore(dbPath);
+
+  // Resolve whether the agent runs in delivery mode (external daemon) or inline dispatcher mode.
+  // If agentSpec is a known daemon runtime (neeko/coco/codex), use it directly.
+  // Otherwise, treat it as a logical agent key and look up its runtime in the DB.
+  let resolvedRuntime: string | null = null;
+  if (agentSpec) {
+    const directRuntime = agentSpec.split(':')[0];
+    if (directRuntime === 'neeko' || directRuntime === 'coco' || directRuntime === 'coco-stream-json' || directRuntime === 'codex') {
+      resolvedRuntime = directRuntime;
+    } else {
+      resolvedRuntime = msgStore.getAgentRuntime(agentSpec);
+      if (!resolvedRuntime) {
+        (log.warn ?? console.warn)(`[lark] agent ${agentSpec} has no runtime configured in DB; defaulting to neeko. Run "bun run src/cli.ts agents create --key ${agentSpec} --name <name> --runtime neeko|coco|coco-stream-json|codex" to configure.`);
+        resolvedRuntime = 'neeko';
+      }
+    }
+  }
+  const isDeliveryAgent = resolvedRuntime === 'neeko' || resolvedRuntime === 'coco' || resolvedRuntime === 'coco-stream-json' || resolvedRuntime === 'codex';
+
+  const dispatchers = new Map<string, { dispatcher: ChatDispatcher; periodic: PeriodicQueue | null; chatIdToLarkChatId: Map<string, string> }>();
+  if (agentSpec && !isDeliveryAgent) {
+    for (const bot of targets) {
+      const runtime = parseRuntimeSpec(agentSpec);
+      const chatIdToLarkChatId = new Map<string, string>();
+      const apiClient = replyToLark ? createLarkApiClient(bot.appId, bot.appSecret) : null;
+      const dispatcher = new ChatDispatcher({
+        runtime,
+        logger: { log: log.log ?? console.log, warn: log.warn, error: log.error },
+        onReply: async ({ chatKey, reply, sourceMessages }) => {
+          const larkChatId = chatIdToLarkChatId.get(chatKey);
+          if (!larkChatId) {
+            (log.warn ?? console.warn)(`[lark/${bot.appId}] no larkChatId mapped for ${chatKey}; reply not sent`);
+            return;
+          }
+          (log.log ?? console.log)(
+            `[lark/${bot.appId}] agent ${runtime.name} replied to chat=${larkChatId} (${reply.text.length} chars) sources=${sourceMessages.length}`,
+          );
+          if (apiClient) {
+            try {
+              const sent = await sendTextMessage({ client: apiClient, receiveIdType: 'chat_id', receiveId: larkChatId, text: reply.text });
+              (log.log ?? console.log)(`[lark/${bot.appId}] sent reply message_id=${sent.messageId ?? '-'}`);
+            } catch (err) {
+              (log.error ?? console.error)(`[lark/${bot.appId}] send failed:`, err);
+            }
+          }
+        },
+      });
+      let periodic: PeriodicQueue | null = null;
+      if (policy === 'periodic') {
+        periodic = new PeriodicQueue({
+          intervalMs: periodicIntervalMs,
+          logger: { log: log.log ?? console.log, warn: log.warn, error: log.error },
+          onFlush: async ({ chatKey, batch }) => {
+            (log.log ?? console.log)(`[lark/${bot.appId}] periodic flush chat=${chatKey} count=${batch.length}`);
+            await dispatcher.enqueueBatch(batch);
+          },
+        });
+        periodic.start();
+      }
+      dispatchers.set(bot.appId, { dispatcher, periodic, chatIdToLarkChatId });
+    }
+    (log.log ?? console.log)(`[lark] dispatcher armed: runtime=${agentSpec} policy=${policy}${policy === 'periodic' ? ` intervalMs=${periodicIntervalMs}` : ''} replyToLark=${replyToLark}`);
+  } else if (isDeliveryAgent) {
+    (log.log ?? console.log)(`[lark] delivery mode: agent=${agentSpec} resolvedRuntime=${resolvedRuntime} policy=${policy}`);
+  }
+  const handles = targets.map((bot) =>
+    startLarkDaemon({
+      appId: bot.appId,
+      appSecret: bot.appSecret,
+      db: msgStore.db,
+      logger: { info: log.log ?? console.log, warn: log.warn, error: log.error },
+      onEvent: ({ envelope, data, storeResult }) => {
+        (log.log ?? console.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 result = ingestLarkMessage({
+              appId: bot.appId,
+              envelope: data as LarkMessageEnvelope,
+              store: msgStore,
+            });
+            if (result.status === 'ok' && result.message) {
+              const tag = result.deduped ? 'dup' : result.threadOrphan ? 'orphan' : 'new';
+              (log.log ?? console.log)(
+                `[lark/${bot.appId}] ingest ${tag} lock_msg=${result.message.id} chat=${result.message.chat_name} parent=${result.message.parent_id ?? '-'}`,
+              );
+              if (tag === 'new') {
+                if (isDeliveryAgent) {
+                  const mentionOpenIds = extractMentionOpenIds(data as LarkMessageEnvelope);
+                  const accept = shouldAcceptForAgent({
+                    policy,
+                    botOpenId: bot.botOpenId ?? null,
+                    mentionOpenIds,
+                  });
+                  if (!accept) {
+                    (log.log ?? console.log)(`[lark/${bot.appId}] policy=${policy} drop (no mention or off)`);
+                  } else {
+                    try {
+                      const delivery = msgStore.createDelivery({ messageId: result.message.id, agent: agentSpec! });
+                      (log.log ?? console.log)(`[lark/${bot.appId}] created delivery id=${delivery.id} for agent=${agentSpec} message=${result.message.id}`);
+                    } catch (err) {
+                      (log.warn ?? console.warn)(`[lark/${bot.appId}] createDelivery failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                  }
+                } else {
+                  const wired = dispatchers.get(bot.appId);
+                  if (wired) {
+                    const mentionOpenIds = extractMentionOpenIds(data as LarkMessageEnvelope);
+                    const larkChatId = (data as LarkMessageEnvelope).message?.chat_id;
+                    if (larkChatId) wired.chatIdToLarkChatId.set(result.message.chat_id, larkChatId);
+                    const input: DispatchInput = {
+                      chatKey: chatKeyOf(result.message),
+                      senderOpenId: result.message.sender,
+                      text: result.message.content,
+                      larkMessageId: result.message.idempotency_key ?? `lock-${result.message.id}`,
+                      lockMessageId: result.message.id,
+                      parentLockMessageId: result.message.parent_id,
+                    };
+                    if (policy === 'periodic' && wired.periodic) {
+                      wired.periodic.add(input);
+                      (log.log ?? console.log)(`[lark/${bot.appId}] policy=periodic buffered chat=${input.chatKey} buf=${wired.periodic.inspect().find((e) => e.chatKey === input.chatKey)?.pending ?? '?'}`);
+                    } else {
+                      const accept = shouldAcceptForAgent({
+                        policy,
+                        botOpenId: bot.botOpenId ?? null,
+                        mentionOpenIds,
+                      });
+                      if (!accept) {
+                        (log.log ?? console.log)(`[lark/${bot.appId}] policy=${policy} drop (no mention or off)`);
+                      } else {
+                        void wired.dispatcher.enqueue(input);
+                      }
+                    }
+                  }
+                }
+              }
+            } else if (result.status === 'skipped') {
+              (log.log ?? console.log)(`[lark/${bot.appId}] ingest skipped reason=${result.reason}`);
+            }
+          } catch (err) {
+            (log.error ?? console.error)(`[lark/${bot.appId}] ingest error:`, err);
+          }
+        }
+      },
+    }),
+  );
+  (log.log ?? console.log)(`[lark] daemon up; bots=${handles.map((h) => h.appId).join(',')}; db=${dbPath}`);
+
+  // Keep the event loop alive so the WSClient connection persists.
+  // The WSClient's internal websocket may not hold the loop in some runtimes.
+  const heartbeat = setInterval(() => {
+    /* no-op: just keeps the process alive */
+  }, 30000);
+
+  return new Promise<number>((resolve) => {
+    const shutdown = (signal: string) => {
+      clearInterval(heartbeat);
+      (log.log ?? console.log)(`[lark] received ${signal}, stopping ${handles.length} bot(s)`);
+      for (const wired of dispatchers.values()) {
+        if (wired.periodic) wired.periodic.stop();
+      }
+      for (const h of handles) h.stop();
+      msgStore.close();
+      resolve(0);
+    };
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGUSR1', () => {
+      for (const [appId, wired] of dispatchers.entries()) {
+        const { redelivered } = wired.dispatcher.restartAll();
+        (log.log ?? console.log)(`[lark/${appId}] SIGUSR1 restart-all redelivered=${redelivered}`);
+      }
+    });
+    process.on('SIGUSR2', () => {
+      for (const [appId, wired] of dispatchers.entries()) {
+        const { aborted, dropped } = wired.dispatcher.killAll();
+        (log.log ?? console.log)(`[lark/${appId}] SIGUSR2 kill-all aborted=${aborted} dropped=${dropped}`);
+      }
+    });
+    // SIGHUP → flush periodic buffers now (operator can use this when they
+    // want to wake the agent without waiting for the next tick).
+    process.on('SIGHUP', () => {
+      for (const [appId, wired] of dispatchers.entries()) {
+        if (wired.periodic) {
+          void wired.periodic.flushAll().then((n) => {
+            (log.log ?? console.log)(`[lark/${appId}] SIGHUP periodic flushAll released=${n}`);
+          });
+        }
+      }
+    });
+  });
+}
+
+async function runSend(argv: LarkCliArgs, log: NonNullable<RunOptions['log']>): Promise<number> {
+  const appId = flagString(argv.flags, 'app-id');
+  const to = flagString(argv.flags, 'to');
+  const toType = (flagString(argv.flags, 'to-type') ?? 'chat_id') as 'chat_id' | 'open_id' | 'union_id' | 'email' | 'user_id';
+  const text = argv.values.slice(1).join(' ').trim() || readStdinSync();
+  const configPath = flagString(argv.flags, 'config') ?? defaultLarkConfigPath();
+  if (!appId) {
+    (log.error ?? console.error)('lark send requires --app-id');
+    return 2;
+  }
+  if (!to) {
+    (log.error ?? console.error)('lark send requires --to');
+    return 2;
+  }
+  if (!text) {
+    (log.error ?? console.error)('lark send requires text (positional arg or stdin)');
+    return 2;
+  }
+  const store = loadLarkCredentials(configPath);
+  const bot = findCredential(store, appId);
+  if (!bot) {
+    (log.error ?? console.error)(`appId ${appId} not found in ${configPath}`);
+    return 2;
+  }
+  const client = createLarkApiClient(bot.appId, bot.appSecret);
+  const result = await sendTextMessage({ client, receiveIdType: toType, receiveId: to, text });
+  printJson({ ok: true, messageId: result.messageId }, { log: log.log });
+  return 0;
+}
+
+function readStdinSync(): string {
+  try {
+    return readFileSync(0, 'utf8').trim();
+  } catch {
+    return '';
+  }
+}

package/src/lark/credentials.ts

@@ -0,0 +1,105 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homeDir } from '../config.js';
+
+export interface LarkCredential {
+  appId: string;
+  appSecret: string;
+  label?: string;
+  agent?: string;
+  botOpenId?: string;
+}
+
+export interface LarkCredentialStore {
+  bots: LarkCredential[];
+}
+
+export function defaultLarkConfigPath(): string {
+  return process.env.PAL_LARK_CONFIG ?? join(homeDir(), 'lark.json');
+}
+
+export function loadLarkCredentials(path: string = defaultLarkConfigPath()): LarkCredentialStore {
+  if (!existsSync(path)) {
+    return { bots: [] };
+  }
+  const raw = readFileSync(path, 'utf8');
+  const parsed = JSON.parse(raw) as unknown;
+  return normalizeStore(parsed);
+}
+
+export function saveLarkCredentials(store: LarkCredentialStore, path: string = defaultLarkConfigPath()): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const serialized = `${JSON.stringify(store, null, 2)}\n`;
+  const tmpPath = `${path}.tmp`;
+  writeFileSync(tmpPath, serialized, { encoding: 'utf8', mode: 0o600 });
+  chmodSync(tmpPath, 0o600);
+  renameSync(tmpPath, path);
+  chmodSync(path, 0o600);
+}
+
+export interface AddCredentialResult {
+  store: LarkCredentialStore;
+  replaced: boolean;
+}
+
+export function upsertCredential(store: LarkCredentialStore, credential: LarkCredential): AddCredentialResult {
+  validateCredential(credential);
+  const existingIndex = store.bots.findIndex((bot) => bot.appId === credential.appId);
+  const next: LarkCredentialStore = { bots: [...store.bots] };
+  if (existingIndex === -1) {
+    next.bots.push(credential);
+    return { store: next, replaced: false };
+  }
+  next.bots[existingIndex] = credential;
+  return { store: next, replaced: true };
+}
+
+export function findCredential(store: LarkCredentialStore, appId: string): LarkCredential | undefined {
+  return store.bots.find((bot) => bot.appId === appId);
+}
+
+export function boundAgents(credential: Pick<LarkCredential, 'agent'>): string[] {
+  const agent = credential.agent?.trim();
+  return agent ? [agent] : [];
+}
+
+function validateCredential(credential: LarkCredential): void {
+  if (!credential.appId || typeof credential.appId !== 'string') {
+    throw new Error('appId is required');
+  }
+  if (!credential.appSecret || typeof credential.appSecret !== 'string') {
+    throw new Error('appSecret is required');
+  }
+}
+
+function normalizeStore(parsed: unknown): LarkCredentialStore {
+  if (parsed && typeof parsed === 'object' && 'bots' in parsed && Array.isArray((parsed as { bots: unknown }).bots)) {
+    const bots = (parsed as { bots: unknown[] }).bots.map((entry, index) => {
+      if (!entry || typeof entry !== 'object') {
+        throw new Error(`bots[${index}] is not an object`);
+      }
+      const obj = entry as Record<string, unknown>;
+      const appId = obj.appId ?? obj.larkAppId;
+      const appSecret = obj.appSecret ?? obj.larkAppSecret;
+      const label = obj.label;
+      const agent = obj.agent;
+      const botOpenId = obj.botOpenId;
+      if (typeof appId !== 'string' || typeof appSecret !== 'string') {
+        throw new Error(`bots[${index}] is missing appId/appSecret`);
+      }
+      if ('agents' in obj) {
+        throw new Error(`bots[${index}].agents is no longer supported; use agent`);
+      }
+      const credential: LarkCredential = { appId, appSecret };
+      if (typeof label === 'string') credential.label = label;
+      if (typeof agent === 'string') credential.agent = agent;
+      if (typeof botOpenId === 'string') credential.botOpenId = botOpenId;
+      return credential;
+    });
+    return { bots };
+  }
+  if (Array.isArray(parsed)) {
+    return normalizeStore({ bots: parsed });
+  }
+  throw new Error('lark.json must be { bots: [...] } or a bots array');
+}