@controlflow-ai/daemon 0.1.0

package/src/lark/event-router.ts

@@ -0,0 +1,329 @@
+import type { MessageStore, CreateMessageInput } from '../db.js';
+import type { Message } from '../types.js';
+import { palIdentityHandle } from '../provider-identity.js';
+
+/**
+ * Map a Lark `im.message.receive_v1` event into a `CreateMessageInput`
+ * suitable for `MessageStore.createMessage`.
+ *
+ * Mapping rules (M2 minimal viable):
+ *
+ * | Lark field                        | pal field            |
+ * |-----------------------------------|---------------------------|
+ * | message.chat_id                   | chatName (prefixed `lark:`) |
+ * | message.message_id                | idempotencyKey            |
+ * | sender.sender_id.open_id          | sender                    |
+ * | message.mentions[0]?.id.open_id   | recipient (first @mention)|
+ * | message.content (parsed JSON text)| content                   |
+ * | message.root_id (thread reply)    | parentId via lookup       |
+ *
+ * Thread mapping: when `message.root_id` is set (i.e. this is a reply inside
+ * a Lark thread/topic), we look up the previously-stored lock message whose
+ * idempotency_key matches `root_id`. If found, the new message becomes a
+ * topic (depth=1, parent=root). If the root is not yet stored (out-of-order
+ * delivery), the reply is stored at top-level under the same chat, with the
+ * Lark root_id preserved in the `recipient` field as `root:<id>` so a later
+ * backfill can wire it up.
+ *
+ * Idempotency: Lark `message_id` is guaranteed-unique per tenant; we feed it
+ * into `idempotency_key` so any retried delivery gets coalesced by the
+ * existing dedupe path in `createMessage`.
+ */
+export interface LarkMessageEnvelope {
+  sender?: {
+    sender_id?: { open_id?: string; user_id?: string; union_id?: string };
+    sender_type?: string;
+  };
+  message?: {
+    message_id?: string;
+    chat_id?: string;
+    chat_type?: string;
+    root_id?: string;
+    thread_id?: string;
+    parent_id?: string;
+    message_type?: string;
+    create_time?: string;
+    content?: string;
+    mentions?: Array<{ id?: { open_id?: string; user_id?: string }; name?: string; key?: string }>;
+  };
+}
+
+export interface MapLarkMessageInput {
+  /** appId of the receiving bot; used to namespace chat names so multiple bots don't collide. */
+  appId: string;
+  envelope: LarkMessageEnvelope;
+  recipientByMentionOpenId?: Map<string, string>;
+  recipientOverride?: string | null;
+}
+
+export interface MapLarkMessageResult {
+  status: 'ok' | 'skipped';
+  reason?: 'missing_message_id' | 'missing_chat_id' | 'missing_sender' | 'unsupported_message_type' | 'empty_text';
+  input?: CreateMessageInput;
+  /** Lark root_id when present (for thread replies). The router pre-resolves the parentId from it if possible. */
+  rootMessageId?: string;
+}
+
+export function buildLockChatName(appId: string, chatId: string, chatType?: string): string {
+  if (chatType === 'group') {
+    return `lark:group:${chatId}`;
+  }
+  return `lark:${appId}:${chatId}`;
+}
+
+/** Extract @mention open_ids from a Lark envelope (may be empty). */
+export function extractMentionOpenIds(envelope: LarkMessageEnvelope): string[] {
+  const mentions = envelope.message?.mentions ?? [];
+  const ids: string[] = [];
+  for (const m of mentions) {
+    const id = m.id?.open_id;
+    if (typeof id === 'string' && id.length > 0) ids.push(id);
+  }
+  return ids;
+}
+
+function normalizeMappedMentions(values: Array<string | null>): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
+  }
+  return out;
+}
+
+function parseLarkTextContent(rawContent: string | undefined, messageType: string | undefined): string {
+  if (!rawContent) return '';
+  if (messageType !== 'text' && messageType !== undefined) {
+    // Non-text messages: keep the raw JSON so downstream agents see *something*.
+    return rawContent.length > 4000 ? rawContent.slice(0, 4000) + '…' : rawContent;
+  }
+  try {
+    const parsed = JSON.parse(rawContent) as { text?: unknown };
+    if (typeof parsed.text === 'string') return parsed.text;
+    return rawContent;
+  } catch {
+    return rawContent;
+  }
+}
+
+/**
+ * Pure mapper: no DB access. Returns a `CreateMessageInput` skeleton (without
+ * parentId resolution — that happens in `resolveThreadParent`).
+ */
+export function mapLarkMessageToCreateInput(input: MapLarkMessageInput): MapLarkMessageResult {
+  const envelope = input.envelope;
+  const msg = envelope.message;
+  const sender = envelope.sender;
+  if (!msg?.message_id) return { status: 'skipped', reason: 'missing_message_id' };
+  if (!msg.chat_id) return { status: 'skipped', reason: 'missing_chat_id' };
+  const senderOpenId = sender?.sender_id?.open_id;
+  if (!senderOpenId) return { status: 'skipped', reason: 'missing_sender' };
+
+  const text = parseLarkTextContent(msg.content, msg.message_type);
+  if (!text.trim()) return { status: 'skipped', reason: 'empty_text' };
+
+  const firstMention = msg.mentions?.find((m) => m.id?.open_id)?.id?.open_id;
+  const mappedMentions = normalizeMappedMentions(msg.mentions?.map((m) => m.id?.open_id ? input.recipientByMentionOpenId?.get(m.id.open_id) ?? null : null) ?? []);
+  const recipient = input.recipientOverride !== undefined
+    ? input.recipientOverride
+    : firstMention ? input.recipientByMentionOpenId?.get(firstMention) ?? firstMention : null;
+  const chatName = buildLockChatName(input.appId, msg.chat_id, msg.chat_type);
+  const rootMessageId = msg.root_id?.trim() || undefined;
+
+  const createInput: CreateMessageInput = {
+    chatName,
+    sender: senderOpenId,
+    recipient,
+    content: text,
+    type: 'message',
+    idempotencyKey: msg.message_id,
+    provider: 'lark',
+    mentions: mappedMentions,
+  };
+
+  return {
+    status: 'ok',
+    input: createInput,
+    rootMessageId,
+  };
+}
+
+/**
+ * Resolve a Lark `root_id` to a previously-stored lock message (by
+ * `idempotency_key == root_id`). Returns null if not found.
+ *
+ * We use `messages.idempotency_key` here because the Lark message_id of the
+ * root was stored there when the root was originally ingested. This is
+ * deterministic and avoids needing a side-table.
+ */
+export function resolveLarkRootMessage(store: MessageStore, rootLarkMessageId: string): Message | null {
+  const row = store.db
+    .query(
+      `SELECT m.*, c.name AS chat_name
+       FROM messages m
+       JOIN chats c ON c.id = m.chat_id
+       WHERE m.idempotency_key = ? AND m.parent_id IS NULL
+       LIMIT 1`,
+    )
+    .get(rootLarkMessageId) as Record<string, unknown> | null;
+  if (!row) return null;
+  return rowToMessage(row);
+}
+
+// Local copy of rowToMessage shape to avoid importing db.ts internals. Keep
+// in sync with src/db.ts:rowToMessage().
+function rowToMessage(row: Record<string, unknown>): Message {
+  return {
+    id: Number(row.id),
+    chat_id: String(row.chat_id),
+    chat_name: String(row.chat_name),
+    parent_id: row.parent_id === null || row.parent_id === undefined ? null : Number(row.parent_id),
+    depth: Number(row.depth) as 0 | 1,
+    sender: String(row.sender),
+    recipient: row.recipient === null || row.recipient === undefined ? null : String(row.recipient),
+    content: String(row.content),
+    type: row.type === 'system' ? 'system' : 'message',
+    created_at: String(row.created_at),
+    idempotency_key: row.idempotency_key === null || row.idempotency_key === undefined ? null : String(row.idempotency_key),
+  };
+}
+
+/**
+ * Full pipeline: map + thread resolution + insert. Returns the resulting
+ * Message (either freshly inserted or coalesced via idempotency).
+ *
+ * Returns null when the event was skipped (non-mappable; e.g. missing fields).
+ */
+export interface IngestLarkMessageInput extends MapLarkMessageInput {
+  store: MessageStore;
+}
+
+export interface IngestLarkMessageResult {
+  status: 'ok' | 'skipped';
+  reason?: MapLarkMessageResult['reason'];
+  message?: Message;
+  /** True when the root_id was set but no parent message was found in the local DB. */
+  threadOrphan?: boolean;
+  /** True when createMessage coalesced via idempotency (i.e. this Lark message_id was already stored). */
+  deduped?: boolean;
+}
+
+export function ingestLarkMessage(input: IngestLarkMessageInput): IngestLarkMessageResult {
+  const account = input.store.getChannelAccountByAppId(input.appId);
+  const providerAccountId = account?.provider_account_id ?? null;
+  const senderOpenId = input.envelope.sender?.sender_id?.open_id?.trim() ?? '';
+  const senderKind = input.envelope.sender?.sender_type === 'app' ? 'bot' : 'user';
+  const senderDisplayName = input.envelope.sender?.sender_id?.union_id ?? input.envelope.sender?.sender_id?.user_id ?? null;
+  const senderHandle = providerAccountId && senderOpenId
+    ? input.store.getOrCreateProviderIdentity({
+        provider: 'lark',
+        providerAccountId,
+        externalType: senderKind,
+        externalId: senderOpenId,
+        displayName: senderDisplayName,
+      }).identity.stable_handle
+    : senderOpenId ? palIdentityHandle(senderKind, `lark:${input.appId}:${senderOpenId}`) : '';
+  const mentionHandles = new Map<string, string>();
+  for (const mention of input.envelope.message?.mentions ?? []) {
+    const mentionOpenId = mention.id?.open_id?.trim();
+    if (!mentionOpenId) continue;
+    if (input.recipientByMentionOpenId?.has(mentionOpenId)) continue;
+    const externalType = account?.bot_open_id === mentionOpenId ? 'bot' : 'user';
+    const handle = providerAccountId
+      ? input.store.getOrCreateProviderIdentity({
+          provider: 'lark',
+          providerAccountId,
+          externalType,
+          externalId: mentionOpenId,
+          displayName: mention.name,
+        }).identity.stable_handle
+      : palIdentityHandle(externalType, `lark:${input.appId}:${mentionOpenId}`);
+    mentionHandles.set(mentionOpenId, handle);
+  }
+  const recipientByMentionOpenId = new Map(input.recipientByMentionOpenId ?? []);
+  for (const [openId, handle] of mentionHandles) {
+    recipientByMentionOpenId.set(openId, handle);
+  }
+  const mapped = mapLarkMessageToCreateInput({
+    appId: input.appId,
+    envelope: input.envelope,
+    recipientByMentionOpenId,
+    recipientOverride: input.recipientOverride,
+  });
+  if (mapped.status !== 'ok' || !mapped.input) {
+    return { status: 'skipped', reason: mapped.reason };
+  }
+  let parentResolved: Message | null = null;
+  let threadOrphan = false;
+  if (mapped.rootMessageId) {
+    parentResolved = resolveLarkRootMessage(input.store, mapped.rootMessageId);
+    if (!parentResolved) {
+      threadOrphan = true;
+    }
+  }
+  const createInput: CreateMessageInput = parentResolved
+    ? {
+        parentId: parentResolved.id,
+        sender: senderHandle || mapped.input.sender,
+        recipient: mapped.input.recipient,
+        content: mapped.input.content,
+        type: mapped.input.type,
+        idempotencyKey: mapped.input.idempotencyKey,
+      }
+    : threadOrphan
+      ? {
+          chatName: mapped.input.chatName,
+          sender: senderHandle || mapped.input.sender,
+          recipient: `root:${mapped.rootMessageId}`,
+          content: mapped.input.content,
+          type: mapped.input.type,
+          idempotencyKey: mapped.input.idempotencyKey,
+        }
+      : { ...mapped.input, sender: senderHandle || mapped.input.sender };
+
+  let deduped = false;
+  if (createInput.idempotencyKey) {
+    const existing = input.store.db
+      .query(
+        `SELECT m.*, c.name AS chat_name
+         FROM messages m
+         JOIN chats c ON c.id = m.chat_id
+         WHERE m.idempotency_key = ?`,
+      )
+      .get(createInput.idempotencyKey) as Record<string, unknown> | null;
+    if (existing) {
+      deduped = true;
+      return {
+        status: 'ok',
+        message: rowToMessage(existing),
+        threadOrphan,
+        deduped,
+      };
+    }
+  }
+  const message = input.store.createMessage(createInput);
+  input.store.upsertRoomParticipant({
+    roomId: message.chat_id,
+    participantId: message.sender,
+    kind: senderKind,
+    displayName: senderDisplayName,
+    source: 'event',
+  });
+
+  for (const mention of input.envelope.message?.mentions ?? []) {
+    const mentionOpenId = mention.id?.open_id;
+    if (!mentionOpenId) continue;
+    const participantId = input.recipientByMentionOpenId?.get(mentionOpenId) ?? mentionHandles.get(mentionOpenId);
+    if (!participantId) continue;
+    input.store.upsertRoomParticipant({
+      roomId: message.chat_id,
+      participantId,
+      kind: account?.bot_open_id === mentionOpenId ? 'bot' : 'user',
+      displayName: mention.name,
+      source: account?.bot_open_id === mentionOpenId ? 'known_bot' : 'event',
+    });
+  }
+  return { status: 'ok', message, threadOrphan, deduped };
+}

package/src/lark/inbound-events.ts

@@ -0,0 +1,131 @@
+import type { Database } from 'bun:sqlite';
+
+export interface InboundRawEvent {
+  id: string;
+  received_at: string;
+  app_id: string;
+  event_type: string;
+  event_id: string;
+  parse_ok: 0 | 1;
+  raw_body_bytes: Uint8Array;
+}
+
+export interface StoreInboundEventInput {
+  appId: string;
+  rawBody: string | Uint8Array;
+}
+
+export interface StoreInboundEventResult {
+  id: string;
+  event_id: string;
+  event_type: string;
+  parse_ok: 0 | 1;
+  inserted: boolean;
+  duplicate: boolean;
+}
+
+const ENCODER = new TextEncoder();
+
+function toBytes(body: string | Uint8Array): Uint8Array {
+  return typeof body === 'string' ? ENCODER.encode(body) : body;
+}
+
+async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  const buf = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+  const digest = await crypto.subtle.digest('SHA-256', buf);
+  const arr = Array.from(new Uint8Array(digest));
+  return arr.map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+export interface ParsedEnvelope {
+  event_id: string;
+  event_type: string;
+  parse_ok: 0 | 1;
+}
+
+export async function parseEventEnvelope(rawBytes: Uint8Array): Promise<ParsedEnvelope> {
+  try {
+    const text = new TextDecoder('utf8', { fatal: false }).decode(rawBytes);
+    const json = JSON.parse(text) as Record<string, unknown>;
+    const header = (json.header && typeof json.header === 'object') ? json.header as Record<string, unknown> : null;
+    const eventId = (header?.event_id ?? json.uuid) as unknown;
+    const eventType = (header?.event_type ?? json.type) as unknown;
+    if (typeof eventId === 'string' && eventId.length > 0 && typeof eventType === 'string' && eventType.length > 0) {
+      return { event_id: eventId, event_type: eventType, parse_ok: 1 };
+    }
+    const fallbackId = `sha256:${await sha256Hex(rawBytes)}`;
+    return {
+      event_id: fallbackId,
+      event_type: typeof eventType === 'string' ? eventType : 'unknown',
+      parse_ok: 0,
+    };
+  } catch {
+    const fallbackId = `sha256:${await sha256Hex(rawBytes)}`;
+    return { event_id: fallbackId, event_type: 'unknown', parse_ok: 0 };
+  }
+}
+
+/**
+ * Insert a raw Lark event into channel_inbound_raw_events.
+ *
+ * Deduplication: the partial UNIQUE index on event_id (WHERE event_id IS NOT
+ * NULL) backs an ON CONFLICT DO NOTHING insert. A duplicate event_id returns
+ * { inserted: false, duplicate: true } so the caller can skip side effects.
+ */
+export async function storeInboundEvent(db: Database, input: StoreInboundEventInput): Promise<StoreInboundEventResult> {
+  const rawBytes = toBytes(input.rawBody);
+  const envelope = await parseEventEnvelope(rawBytes);
+  const id = crypto.randomUUID();
+  const result = db
+    .query(
+      `INSERT INTO channel_inbound_raw_events (id, app_id, event_type, event_id, parse_ok, raw_body_bytes)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(event_id) WHERE event_id IS NOT NULL DO NOTHING
+       RETURNING id`,
+    )
+    .get(id, input.appId, envelope.event_type, envelope.event_id, envelope.parse_ok, rawBytes) as { id: string } | null;
+
+  if (result) {
+    return {
+      id: result.id,
+      event_id: envelope.event_id,
+      event_type: envelope.event_type,
+      parse_ok: envelope.parse_ok,
+      inserted: true,
+      duplicate: false,
+    };
+  }
+  const existing = db
+    .query('SELECT id FROM channel_inbound_raw_events WHERE event_id = ? LIMIT 1')
+    .get(envelope.event_id) as { id: string } | null;
+  return {
+    id: existing?.id ?? id,
+    event_id: envelope.event_id,
+    event_type: envelope.event_type,
+    parse_ok: envelope.parse_ok,
+    inserted: false,
+    duplicate: true,
+  };
+}
+
+export function getInboundEvent(db: Database, id: string): InboundRawEvent | null {
+  const row = db
+    .query('SELECT id, received_at, app_id, event_type, event_id, parse_ok, raw_body_bytes FROM channel_inbound_raw_events WHERE id = ?')
+    .get(id) as InboundRawEvent | null;
+  return row;
+}
+
+export function listRecentInboundEvents(db: Database, limit = 20): InboundRawEvent[] {
+  return db
+    .query('SELECT id, received_at, app_id, event_type, event_id, parse_ok, raw_body_bytes FROM channel_inbound_raw_events ORDER BY received_at DESC, id DESC LIMIT ?')
+    .all(Math.max(1, Math.min(limit, 500))) as InboundRawEvent[];
+}
+
+export function countInboundEvents(db: Database, appId?: string): number {
+  if (appId) {
+    const row = db.query('SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE app_id = ?').get(appId) as { n: number };
+    return row.n;
+  }
+  const row = db.query('SELECT COUNT(*) AS n FROM channel_inbound_raw_events').get() as { n: number };
+  return row.n;
+}