@controlflow-ai/daemon 0.1.0

package/src/lark/daemon-integration.ts

@@ -0,0 +1,108 @@
+import type { Database } from 'bun:sqlite';
+import { MessageStore } from '../db.js';
+import { loadLarkCredentials, type LarkCredential } from './credentials.js';
+import { extractMentionOpenIds, ingestLarkMessage, type LarkMessageEnvelope } from './event-router.js';
+import { shouldAcceptForAgent, type ReceivePolicy } from './dispatcher.js';
+import { startLarkDaemon, type LarkDaemonHandle } from './ws-daemon.js';
+
+export interface LarkIntegrationOptions {
+  agent: string;
+  /** Shared MessageStore for DB operations (caller owns lifecycle). */
+  store: MessageStore;
+  policy?: ReceivePolicy;
+  botOpenIdByApp?: Map<string, string>;
+  logger?: Partial<Pick<Console, 'log' | 'warn' | 'error'>>;
+}
+
+export interface LarkIntegrationResult {
+  handles: LarkDaemonHandle[];
+  stop(): void;
+}
+
+/**
+ * Find Lark bots bound to the given agent key in lark.json.
+ */
+export function findLarkBotsForAgent(agent: string, configPath?: string): LarkCredential[] {
+  const store = loadLarkCredentials(configPath);
+  return store.bots.filter((b) => b.agent === agent);
+}
+
+/**
+ * Start Lark WS connections for the given agent.
+ * When a message arrives, it is ingested into the DB and a delivery is created
+ * for the agent (delivery mode, same as the standalone lark daemon).
+ */
+export function startLarkForAgent(options: LarkIntegrationOptions): LarkIntegrationResult {
+  const log = {
+    log: options.logger?.log ?? console.log,
+    warn: options.logger?.warn ?? console.warn,
+    error: options.logger?.error ?? console.error,
+  };
+  const policy = options.policy ?? 'every';
+  const msgStore = options.store;
+  const botOpenIdByApp = options.botOpenIdByApp ?? new Map<string, string>();
+
+  const bots = findLarkBotsForAgent(options.agent);
+  if (bots.length === 0) {
+    return { handles: [], stop() {} };
+  }
+
+  log.log(`[lark] integrating ${bots.length} bot(s) for agent=${options.agent} policy=${policy}`);
+
+  const handles = bots.map((bot) =>
+    startLarkDaemon({
+      appId: bot.appId,
+      appSecret: bot.appSecret,
+      db: msgStore.db,
+      logger: { info: log.log, warn: log.warn, error: log.error },
+      onEvent: ({ 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 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(
+                `[lark/${bot.appId}] ingest ${tag} lock_msg=${result.message.id} chat=${result.message.chat_name} parent=${result.message.parent_id ?? '-'}`,
+              );
+              if (tag === 'new') {
+                const mentionOpenIds = extractMentionOpenIds(data as LarkMessageEnvelope);
+                const accept = shouldAcceptForAgent({
+                  policy,
+                  botOpenId: botOpenIdByApp.get(bot.appId) ?? null,
+                  mentionOpenIds,
+                });
+                if (!accept) {
+                  log.log(`[lark/${bot.appId}] policy=${policy} drop (no mention or off)`);
+                } else {
+                  try {
+                    const delivery = msgStore.createDelivery({ messageId: result.message.id, agent: options.agent });
+                    log.log(`[lark/${bot.appId}] created delivery id=${delivery.id} for agent=${options.agent} message=${result.message.id}`);
+                  } catch (err) {
+                    log.warn(`[lark/${bot.appId}] createDelivery failed: ${err instanceof Error ? err.message : String(err)}`);
+                  }
+                }
+              }
+            } else if (result.status === 'skipped') {
+              log.log(`[lark/${bot.appId}] ingest skipped reason=${result.reason}`);
+            }
+          } catch (err) {
+            log.error(`[lark/${bot.appId}] ingest error:`, err);
+          }
+        }
+      },
+    }),
+  );
+
+  return {
+    handles,
+    stop() {
+      for (const h of handles) h.stop();
+      log.log(`[lark] stopped ${handles.length} bot(s) for agent=${options.agent}`);
+    },
+  };
+}

package/src/lark/dispatcher.ts

@@ -0,0 +1,374 @@
+import type { Message } from '../types.js';
+import type { AgentInvocation, AgentReply, AgentRuntime } from './agent-runtime.js';
+
+export interface ChatDispatcherDeps {
+  runtime: AgentRuntime;
+  /** Called when the runtime produces a non-empty reply. Implementations
+   *  typically forward it to Lark via sendTextMessage. */
+  onReply: (input: { chatKey: string; reply: AgentReply; sourceMessages: DispatchInput[] }) => Promise<void> | void;
+  /** Optional structured logger. */
+  logger?: Partial<Pick<Console, 'log' | 'warn' | 'error'>>;
+}
+
+export interface DispatchInput {
+  chatKey: string;
+  senderOpenId: string;
+  text: string;
+  larkMessageId: string;
+  lockMessageId: number;
+  parentLockMessageId: number | null;
+  /** When true, the message reached the runtime previously but the run
+   *  was aborted/failed before producing a reply. The dispatcher attaches
+   *  this on re-delivery after restart(). */
+  isRedelivery?: boolean;
+}
+
+interface PendingItem {
+  input: DispatchInput;
+  resolve: () => void;
+}
+
+interface InFlight {
+  batch: PendingItem[];
+  abortController: AbortController;
+}
+
+interface ChatQueueState {
+  pending: PendingItem[];
+  /** Set when a runtime call is currently in progress for this chat. */
+  inFlight: InFlight | null;
+}
+
+/**
+ * Per-chat serial dispatcher.
+ *
+ * Semantics (matches wiki "消息正在处理时, 之后消息堆积; 处理完成后拼接"):
+ *
+ *   - If the chat queue is idle, the new message immediately triggers a
+ *     runtime run with `messages = [thisMessage]`, `isFresh = true`.
+ *   - If the chat queue is busy, the new message is appended to the pending
+ *     buffer. When the current run completes, all accumulated pending
+ *     messages are flushed in a single next invocation with `isFresh = false`.
+ *   - Runtime errors are logged but do NOT block the queue.
+ *   - Different chats progress independently.
+ *
+ * Kill / restart (wiki: "daemon 提供 kill 并重启, 重启后未完成消息重发"):
+ *
+ *   - `killChat(chatKey)` fires the AbortSignal on the in-flight invocation
+ *     and clears the queue. Runtimes that respect the signal should bail out;
+ *     the kill returns the in-flight batch + the pending tail so the caller
+ *     can inspect what was dropped.
+ *   - `restartChat(chatKey)` is `killChat` + re-enqueue of the killed
+ *     in-flight batch with `isRedelivery=true`. This implements the wiki
+ *     guarantee that messages that did not get a successful reply are
+ *     re-delivered after restart.
+ */
+export class ChatDispatcher {
+  private readonly queues = new Map<string, ChatQueueState>();
+
+  constructor(private readonly deps: ChatDispatcherDeps) {}
+
+  get activeChatCount(): number {
+    return this.queues.size;
+  }
+
+  inspect(): Array<{ chatKey: string; pending: number; running: boolean }> {
+    return Array.from(this.queues.entries()).map(([chatKey, state]) => ({
+      chatKey,
+      pending: state.pending.length,
+      running: state.inFlight !== null,
+    }));
+  }
+
+  enqueue(input: DispatchInput): Promise<void> {
+    return this.enqueueBatch([input]);
+  }
+
+  /**
+   * Enqueue multiple messages as a single logical batch. If the chat is
+   * idle, all items run in one runtime invocation (`messages = [...]`,
+   * `isFresh = true`). If the chat is busy, all items are appended to
+   * pending and will be flushed together in the next run.
+   */
+  enqueueBatch(inputs: DispatchInput[]): Promise<void> {
+    if (inputs.length === 0) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      const chatKey = inputs[0].chatKey;
+      // Ensure all inputs share the same chatKey; reject heterogeneous batches.
+      for (const inp of inputs) {
+        if (inp.chatKey !== chatKey) {
+          throw new Error('enqueueBatch requires all inputs to share chatKey');
+        }
+      }
+      let state = this.queues.get(chatKey);
+      if (!state) {
+        state = { pending: [], inFlight: null };
+        this.queues.set(chatKey, state);
+      }
+      let outstanding = inputs.length;
+      const settle = (): void => {
+        outstanding -= 1;
+        if (outstanding <= 0) resolve();
+      };
+      const items: PendingItem[] = inputs.map((inp) => ({ input: inp, resolve: settle }));
+      if (state.inFlight) {
+        state.pending.push(...items);
+        return;
+      }
+      const ctl = new AbortController();
+      state.inFlight = { batch: items, abortController: ctl };
+      void this.dispatch(chatKey, items, true, ctl.signal);
+    });
+  }
+
+  /**
+   * Abort the in-flight run (if any) and drop pending messages.
+   * Returns the messages that were either in flight or queued.
+   * Pending resolvers are still resolved (they are no longer queued).
+   */
+  killChat(chatKey: string): { aborted: DispatchInput[]; dropped: DispatchInput[] } {
+    const state = this.queues.get(chatKey);
+    if (!state) return { aborted: [], dropped: [] };
+    const aborted = state.inFlight ? state.inFlight.batch.map((b) => b.input) : [];
+    const dropped = state.pending.map((p) => p.input);
+    // Resolve all queued pending so callers don't hang.
+    for (const p of state.pending) p.resolve();
+    state.pending = [];
+    if (state.inFlight) state.inFlight.abortController.abort();
+    // We leave inFlight set so dispatch() can detect the abort and clean up.
+    return { aborted, dropped };
+  }
+
+  /**
+   * Kill current activity and re-enqueue the in-flight + pending messages
+   * for a fresh run. The re-enqueued items carry `isRedelivery=true`.
+   * Returns the count of re-enqueued messages.
+   */
+  restartChat(chatKey: string): { redelivered: number } {
+    const { aborted, dropped } = this.killChat(chatKey);
+    const all = [...aborted, ...dropped];
+    for (const item of all) {
+      void this.enqueue({ ...item, isRedelivery: true });
+    }
+    return { redelivered: all.length };
+  }
+
+  /** Kill every chat. Returns aggregate counts. */
+  killAll(): { aborted: number; dropped: number } {
+    let aborted = 0;
+    let dropped = 0;
+    for (const chatKey of Array.from(this.queues.keys())) {
+      const result = this.killChat(chatKey);
+      aborted += result.aborted.length;
+      dropped += result.dropped.length;
+    }
+    return { aborted, dropped };
+  }
+
+  /** Restart every chat (kill + re-enqueue). */
+  restartAll(): { redelivered: number } {
+    let redelivered = 0;
+    for (const chatKey of Array.from(this.queues.keys())) {
+      redelivered += this.restartChat(chatKey).redelivered;
+    }
+    return { redelivered };
+  }
+
+  private async dispatch(chatKey: string, batch: PendingItem[], isFresh: boolean, signal: AbortSignal): Promise<void> {
+    const invocation: AgentInvocation = {
+      chatKey,
+      isFresh,
+      isRedelivery: batch.some((b) => b.input.isRedelivery),
+      messages: batch.map((b) => ({
+        senderOpenId: b.input.senderOpenId,
+        text: b.input.text,
+        larkMessageId: b.input.larkMessageId,
+        lockMessageId: b.input.lockMessageId,
+        parentLockMessageId: b.input.parentLockMessageId,
+      })),
+      signal,
+    };
+    let reply: AgentReply | null = null;
+    let aborted = false;
+    try {
+      reply = await this.deps.runtime.run(invocation);
+    } catch (err) {
+      if (signal.aborted) {
+        aborted = true;
+        this.log('log', `runtime ${this.deps.runtime.name} aborted on ${chatKey}`);
+      } else {
+        this.log('error', `runtime ${this.deps.runtime.name} threw on ${chatKey}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      reply = null;
+    }
+    if (!aborted && reply && reply.text && reply.text.trim().length > 0) {
+      try {
+        await this.deps.onReply({ chatKey, reply, sourceMessages: batch.map((b) => b.input) });
+      } catch (err) {
+        this.log('error', `onReply threw on ${chatKey}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    for (const item of batch) item.resolve();
+    const state = this.queues.get(chatKey);
+    if (!state) return;
+    if (state.pending.length === 0) {
+      state.inFlight = null;
+      this.queues.delete(chatKey);
+      return;
+    }
+    const nextBatch = state.pending.splice(0);
+    const ctl = new AbortController();
+    state.inFlight = { batch: nextBatch, abortController: ctl };
+    void this.dispatch(chatKey, nextBatch, false, ctl.signal);
+  }
+
+  private log(level: 'log' | 'warn' | 'error', msg: string): void {
+    const logger = this.deps.logger ?? console;
+    const fn = logger[level] ?? console[level] ?? console.log;
+    fn(`[dispatcher] ${msg}`);
+  }
+}
+
+/** Build a chat key suitable for the dispatcher from a Message row. */
+export function chatKeyOf(message: Pick<Message, 'chat_id' | 'chat_name'>): string {
+  return message.chat_id;
+}
+
+// ─── Receive policy ────────────────────────────────────────────────────────
+
+export type ReceivePolicy = 'every' | 'mention' | 'periodic' | 'off';
+
+export function parseReceivePolicy(spec: string | undefined | null, fallback: ReceivePolicy = 'every'): ReceivePolicy {
+  const v = (spec ?? '').trim().toLowerCase();
+  if (v === 'every' || v === '') return spec ? 'every' : fallback;
+  if (v === 'mention' || v === 'mention-only' || v === 'm') return 'mention';
+  if (v === 'periodic' || v === 'pull' || v === 'p') return 'periodic';
+  if (v === 'off' || v === 'none' || v === 'silent') return 'off';
+  throw new Error(`unknown receive policy: ${spec}`);
+}
+
+export interface PolicyCheckInput {
+  policy: ReceivePolicy;
+  /** Bot's own open_id (for mention matching). */
+  botOpenId: string | null;
+  mentionOpenIds: string[];
+}
+
+/**
+ * Decide whether a freshly-ingested message should reach the agent
+ * dispatcher *immediately*. Note that `periodic` returns false here —
+ * caller is expected to route those messages into PeriodicQueue.add
+ * instead so they get flushed on the next tick.
+ */
+export function shouldAcceptForAgent(input: PolicyCheckInput): boolean {
+  if (input.policy === 'off') return false;
+  if (input.policy === 'periodic') return false;
+  if (input.policy === 'every') return true;
+  // mention-only: require bot's open_id to appear in mention list.
+  if (!input.botOpenId) return false;
+  return input.mentionOpenIds.includes(input.botOpenId);
+}
+
+// ─── Periodic accumulator ──────────────────────────────────────────────────
+
+export interface PeriodicQueueDeps {
+  intervalMs: number;
+  /** Called once per chat per tick with the accumulated batch.
+   *  Implementation typically calls dispatcher.enqueue(...) once per item
+   *  (the dispatcher will then coalesce them per its own semantics). */
+  onFlush: (input: { chatKey: string; batch: DispatchInput[] }) => Promise<void> | void;
+  logger?: Partial<Pick<Console, 'log' | 'warn' | 'error'>>;
+}
+
+/**
+ * Per-chat accumulator that flushes on a fixed interval. Used to implement
+ * the wiki's "定期 pull" agent receive strategy: rather than dispatching on
+ * every incoming message, messages buffer until the timer ticks; then they
+ * are released to the agent in one batch.
+ *
+ * Lifecycle:
+ *   - `start()` arms the interval timer.
+ *   - `add(input)` enqueues a message for its chatKey.
+ *   - `flushChat(chatKey)` releases that chat's buffer immediately.
+ *   - `flushAll()` releases everything.
+ *   - `stop()` clears the timer and releases nothing.
+ *
+ * Concurrency: tick handler is async; if a tick fires while the previous
+ * tick is still in flight, the new tick still runs (we never block ticks).
+ */
+export class PeriodicQueue {
+  private readonly buffers = new Map<string, DispatchInput[]>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private stopped = false;
+
+  constructor(private readonly deps: PeriodicQueueDeps) {
+    if (deps.intervalMs <= 0) {
+      throw new Error('intervalMs must be > 0');
+    }
+  }
+
+  start(): void {
+    if (this.timer || this.stopped) return;
+    this.timer = setInterval(() => {
+      void this.flushAll();
+    }, this.deps.intervalMs);
+    // Don't block process exit on the periodic tick.
+    if (typeof (this.timer as { unref?: () => void }).unref === 'function') {
+      (this.timer as { unref: () => void }).unref();
+    }
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** Add a message to its chat's buffer. */
+  add(input: DispatchInput): void {
+    if (this.stopped) return;
+    let buf = this.buffers.get(input.chatKey);
+    if (!buf) {
+      buf = [];
+      this.buffers.set(input.chatKey, buf);
+    }
+    buf.push(input);
+  }
+
+  /** Buffered counts per chat, for tests / introspection. */
+  inspect(): Array<{ chatKey: string; pending: number }> {
+    return Array.from(this.buffers.entries()).map(([chatKey, buf]) => ({ chatKey, pending: buf.length }));
+  }
+
+  /** Flush a single chat now. Returns the count released. */
+  async flushChat(chatKey: string): Promise<number> {
+    const buf = this.buffers.get(chatKey);
+    if (!buf || buf.length === 0) return 0;
+    const batch = buf.splice(0);
+    this.buffers.delete(chatKey);
+    try {
+      await this.deps.onFlush({ chatKey, batch });
+    } catch (err) {
+      this.log('error', `onFlush threw on ${chatKey}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return batch.length;
+  }
+
+  /** Flush every chat. Returns the total count released. */
+  async flushAll(): Promise<number> {
+    if (this.buffers.size === 0) return 0;
+    let total = 0;
+    for (const chatKey of Array.from(this.buffers.keys())) {
+      total += await this.flushChat(chatKey);
+    }
+    return total;
+  }
+
+  private log(level: 'log' | 'warn' | 'error', msg: string): void {
+    const logger = this.deps.logger ?? console;
+    const fn = logger[level] ?? console[level] ?? console.log;
+    fn(`[periodic] ${msg}`);
+  }
+}