@runwingman/flightdeck-cli 0.2.0

package/src/chat-runtime.js

@@ -0,0 +1,782 @@
+import { getMeta, getRow, getRows, putMeta } from './db.js';
+import { BotHelperError } from './bot-helpers.js';
+import { normalizeChannelParticipants, normalizeThreadId } from './bot-helpers.js';
+
+const CHAT_RUNTIME_CONTEXT_META_KEY = 'chat_runtime:current';
+const CHAT_TOKEN_STOP_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'been', 'before', 'but', 'by',
+  'can', 'chat', 'chats', 'could', 'did', 'do', 'does', 'find', 'for', 'from', 'had', 'has', 'have',
+  'here', 'how', 'i', 'if', 'in', 'into', 'is', 'it', 'its', 'just', 'me',
+  'more', 'need', 'of', 'on', 'or', 'our', 'please', 'show', 'so', 'than',
+  'that', 'the', 'their', 'them', 'there', 'these', 'they', 'this', 'those',
+  'thread', 'threads', 'to', 'topic', 'us', 'was', 'we', 'were', 'what',
+  'when', 'where', 'which', 'who', 'with', 'you', 'your', 'previous',
+]);
+
+function parseJson(value, fallback) {
+  if (value == null || value === '') return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+function clampLimit(value, fallback, max) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.min(parsed, max);
+}
+
+function truncateText(value, maxLength = 160) {
+  const source = String(value || '').replace(/\s+/g, ' ').trim();
+  if (!source) return '';
+  return source.length > maxLength ? `${source.slice(0, maxLength - 3)}...` : source;
+}
+
+function parseCursor(cursor) {
+  if (!cursor) return 0;
+  const value = String(cursor).trim();
+  const match = value.match(/^offset:(\d+)$/);
+  if (!match) throw new Error(`Invalid cursor: ${cursor}`);
+  return Number.parseInt(match[1], 10);
+}
+
+function encodeCursor(offset) {
+  return `offset:${offset}`;
+}
+
+function tokenizeText(value) {
+  const matches = String(value || '').toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
+  return [...new Set(matches.filter((token) => !CHAT_TOKEN_STOP_WORDS.has(token)))];
+}
+
+function intersectSorted(left = [], right = [], limit = 5) {
+  const rightSet = new Set(right);
+  return [...new Set(left.filter((value) => rightSet.has(value)))].sort().slice(0, limit);
+}
+
+function maxIsoTimestamp(left = '', right = '') {
+  return String(left || '').localeCompare(String(right || '')) >= 0 ? left : right;
+}
+
+function threadKey(channelId, threadId) {
+  return `${channelId}:${threadId}`;
+}
+
+function parseChannelRow(row) {
+  if (!row) return null;
+  const raw = row.raw_json ? JSON.parse(row.raw_json) : {};
+  return {
+    ...raw,
+    record_id: raw.record_id ?? row.record_id,
+    owner_npub: raw.owner_npub ?? row.owner_npub,
+    title: raw.title ?? row.title ?? '',
+    participant_npubs: Array.isArray(raw.participant_npubs)
+      ? raw.participant_npubs
+      : parseJson(row.participant_npubs_json, []),
+    group_ids: Array.isArray(raw.group_ids)
+      ? raw.group_ids
+      : parseJson(row.group_ids_json, []),
+    record_state: raw.record_state ?? row.record_state ?? 'active',
+    updated_at: raw.updated_at ?? row.updated_at ?? '',
+  };
+}
+
+function parseMessageRow(row) {
+  if (!row) return null;
+  const raw = row.raw_json ? JSON.parse(row.raw_json) : {};
+  return {
+    ...raw,
+    record_id: raw.record_id ?? row.record_id,
+    owner_npub: raw.owner_npub ?? row.owner_npub,
+    channel_id: raw.channel_id ?? row.channel_id,
+    parent_message_id: raw.parent_message_id ?? row.parent_message_id ?? null,
+    body: raw.body ?? row.body ?? '',
+    attachments: Array.isArray(raw.attachments)
+      ? raw.attachments
+      : parseJson(row.attachments_json, []),
+    sender_npub: raw.sender_npub ?? row.sender_npub ?? row.owner_npub ?? null,
+    record_state: raw.record_state ?? row.record_state ?? 'active',
+    updated_at: raw.updated_at ?? row.updated_at ?? '',
+  };
+}
+
+function formatMessage(message) {
+  return {
+    message_id: message.record_id,
+    parent_message_id: message.parent_message_id ?? null,
+    sender_npub: message.sender_npub ?? null,
+    body: message.body ?? '',
+    attachments: Array.isArray(message.attachments) ? message.attachments : [],
+    updated_at: message.updated_at ?? '',
+  };
+}
+
+function buildThreadRuntime(channel, messages) {
+  const root = messages[0];
+  const last = latestThreadMessage(messages);
+  const participants = normalizeChannelParticipants(channel);
+  const tokenSource = messages.map((message) => message.body ?? '').join(' ');
+  const tokens = tokenizeText(tokenSource);
+  return {
+    key: threadKey(channel.record_id, root.thread_id),
+    channel_id: channel.record_id,
+    channel_title: channel.title ?? '',
+    thread_id: root.thread_id,
+    root_message_id: root.record_id,
+    last_message_id: last?.record_id ?? root.record_id,
+    message_count: messages.length,
+    updated_at: last?.updated_at ?? root.updated_at ?? '',
+    participants,
+    summary: truncateText(root.body || last?.body || ''),
+    tokens,
+    messages,
+  };
+}
+
+function formatThreadSummary(threadRuntime) {
+  return {
+    channel_id: threadRuntime.channel_id,
+    channel_title: threadRuntime.channel_title,
+    thread_id: threadRuntime.thread_id,
+    root_message_id: threadRuntime.root_message_id,
+    last_message_id: threadRuntime.last_message_id,
+    message_count: threadRuntime.message_count,
+    updated_at: threadRuntime.updated_at,
+    summary: threadRuntime.summary,
+    participants: threadRuntime.participants,
+  };
+}
+
+function getStoredRuntimeContext(db) {
+  return parseJson(getMeta(db, CHAT_RUNTIME_CONTEXT_META_KEY), null);
+}
+
+function setStoredRuntimeContext(db, context) {
+  putMeta(db, CHAT_RUNTIME_CONTEXT_META_KEY, JSON.stringify(context));
+}
+
+function buildChannelRuntimeFromRows(channel, messageRows) {
+  const messages = messageRows.map(parseMessageRow);
+  const byId = new Map(messages.map((message) => [message.record_id, message]));
+
+  const lookupMessage = (messageId) => byId.get(messageId) ?? null;
+  const enrichedMessages = messages.map((message) => {
+    try {
+      return {
+        ...message,
+        thread_id: normalizeThreadId(message, { lookupMessage }),
+      };
+    } catch (error) {
+      if (!(error instanceof BotHelperError) || error.code !== 'thread_unresolved') {
+        throw error;
+      }
+      return {
+        ...message,
+        thread_id: message.record_id,
+        thread_resolution_error: error.message,
+      };
+    }
+  });
+
+  const threads = new Map();
+  for (const message of enrichedMessages) {
+    const bucket = threads.get(message.thread_id) ?? [];
+    bucket.push(message);
+    threads.set(message.thread_id, bucket);
+  }
+
+  const threadRuntimes = new Map(
+    [...threads.entries()].map(([threadId, threadMessages]) => [
+      threadId,
+      buildThreadRuntime(channel, threadMessages),
+    ]),
+  );
+
+  return {
+    channel,
+    messages: enrichedMessages,
+    byId: new Map(enrichedMessages.map((message) => [message.record_id, message])),
+    threads,
+    threadRuntimes,
+  };
+}
+
+function latestThreadMessage(threadMessages = []) {
+  return threadMessages.length > 0 ? threadMessages[threadMessages.length - 1] : null;
+}
+
+function buildChannelRuntime(db, channelId) {
+  const channelRow = getRow(
+    db,
+    `SELECT * FROM channels WHERE record_id = ? AND record_state != 'deleted'`,
+    [channelId],
+  );
+  if (!channelRow) throw new Error(`Channel not found locally: ${channelId}`);
+
+  const channel = parseChannelRow(channelRow);
+  const messageRows = getRows(
+    db,
+    `SELECT * FROM messages
+      WHERE channel_id = ? AND record_state != 'deleted'
+      ORDER BY updated_at ASC, record_id ASC`,
+    [channelId],
+  );
+  return buildChannelRuntimeFromRows(channel, messageRows);
+}
+
+function buildWorkspaceRuntime(db) {
+  const channelRows = getRows(
+    db,
+    `SELECT * FROM channels WHERE record_state != 'deleted' ORDER BY updated_at DESC, record_id ASC`,
+  );
+  const messageRows = getRows(
+    db,
+    `SELECT * FROM messages WHERE record_state != 'deleted' ORDER BY channel_id ASC, updated_at ASC, record_id ASC`,
+  );
+
+  const messageRowsByChannel = new Map();
+  for (const row of messageRows) {
+    const bucket = messageRowsByChannel.get(row.channel_id) ?? [];
+    bucket.push(row);
+    messageRowsByChannel.set(row.channel_id, bucket);
+  }
+
+  const channels = new Map();
+  const channelRuntimes = new Map();
+  const threadsByKey = new Map();
+  const allMessages = [];
+  for (const row of channelRows) {
+    const channel = parseChannelRow(row);
+    channels.set(channel.record_id, channel);
+    const channelRuntime = buildChannelRuntimeFromRows(
+      channel,
+      messageRowsByChannel.get(channel.record_id) ?? [],
+    );
+    channelRuntimes.set(channel.record_id, channelRuntime);
+    allMessages.push(...channelRuntime.messages);
+    for (const threadRuntime of channelRuntime.threadRuntimes.values()) {
+      threadsByKey.set(threadRuntime.key, threadRuntime);
+    }
+  }
+
+  return {
+    channels,
+    channelRuntimes,
+    threadsByKey,
+    messages: allMessages,
+  };
+}
+
+function relationScopeForContext(message, context) {
+  if (message.channel_id === context.channel_id && message.thread_id === context.thread_id) return 'current_thread';
+  if (message.channel_id === context.channel_id) return 'same_channel';
+  return 'other_channel';
+}
+
+function searchScoreForMessage(message, threadRuntime, context, queryLower, queryTokens) {
+  const searchText = [
+    message.body ?? '',
+    threadRuntime.summary ?? '',
+    threadRuntime.channel_title ?? '',
+  ].join(' ').toLowerCase();
+  const exactMatches = queryLower ? Number(searchText.includes(queryLower)) : 0;
+  const tokenMatches = queryTokens.filter((token) => searchText.includes(token));
+  if (exactMatches === 0 && tokenMatches.length === 0) return null;
+  const scope = relationScopeForContext(message, context);
+  const scopeRank = scope === 'current_thread' ? 0 : scope === 'same_channel' ? 1 : 2;
+  return {
+    exactMatches,
+    tokenMatches,
+    scope,
+    scopeRank,
+  };
+}
+
+function relatedScoreForThread(candidate, current) {
+  const sharedTerms = intersectSorted(current.tokens, candidate.tokens, 4);
+  const sharedParticipants = intersectSorted(current.participants, candidate.participants, 6);
+  const sameChannel = candidate.channel_id === current.channel_id;
+  if (!sameChannel && sharedTerms.length === 0) return null;
+  return {
+    sameChannel,
+    sharedTerms,
+    sharedParticipants,
+    matchScore: (sharedTerms.length * 10) + (sharedParticipants.length * 2) + (sameChannel ? 4 : 0),
+  };
+}
+
+function normalizeReferenceInput(values = []) {
+  const input = Array.isArray(values) ? values : [values];
+  const refs = [];
+  for (const value of input) {
+    const ref = String(value || '').trim();
+    if (!ref) continue;
+    let type = null;
+    let id = null;
+    let match = ref.match(/^mention:(chat_message|message|thread|channel):(.+)$/i);
+    if (match) {
+      type = match[1].toLowerCase();
+      id = match[2].trim();
+    } else {
+      match = ref.match(/^(chat_message|message|msg|thread|channel):(.+)$/i);
+      if (match) {
+        type = match[1].toLowerCase();
+        id = match[2].trim();
+      }
+    }
+
+    if (!type || !id) continue;
+    if (type === 'msg' || type === 'chat_message') type = 'message';
+    refs.push({ reference: ref, type, id });
+  }
+  return refs;
+}
+
+function resolveStructuredReferences(db, workspaceRuntime, values = []) {
+  const references = normalizeReferenceInput(values);
+  const resolved = [];
+  for (const ref of references.slice(0, 5)) {
+    if (ref.type === 'message') {
+      const row = getRow(db, `SELECT * FROM messages WHERE record_id = ? AND record_state != 'deleted'`, [ref.id]);
+      if (!row) continue;
+      const message = parseMessageRow(row);
+      const threadRuntime = workspaceRuntime.threadsByKey.get(threadKey(message.channel_id, normalizeThreadId(message, {
+        lookupMessage(messageId) {
+          const messageRow = getRow(db, `SELECT * FROM messages WHERE record_id = ? AND record_state != 'deleted'`, [messageId]);
+          return messageRow ? parseMessageRow(messageRow) : null;
+        },
+      })));
+      if (!threadRuntime) continue;
+      resolved.push({
+        reference: ref.reference,
+        kind: 'message',
+        message_id: message.record_id,
+        channel_id: message.channel_id,
+        channel_title: threadRuntime.channel_title,
+        thread_id: threadRuntime.thread_id,
+        body: message.body ?? '',
+        updated_at: message.updated_at ?? '',
+      });
+      continue;
+    }
+
+    if (ref.type === 'thread') {
+      const row = getRow(db, `SELECT * FROM messages WHERE record_id = ? AND record_state != 'deleted'`, [ref.id]);
+      if (!row) continue;
+      const root = parseMessageRow(row);
+      if (root.parent_message_id) continue;
+      const threadRuntime = workspaceRuntime.threadsByKey.get(threadKey(root.channel_id, root.record_id));
+      if (!threadRuntime) continue;
+      resolved.push({
+        reference: ref.reference,
+        kind: 'thread',
+        ...formatThreadSummary(threadRuntime),
+      });
+      continue;
+    }
+
+    if (ref.type === 'channel') {
+      const channel = workspaceRuntime.channels.get(ref.id);
+      const channelRuntime = workspaceRuntime.channelRuntimes.get(ref.id);
+      if (!channel || !channelRuntime) continue;
+      const threads = [...channelRuntime.threadRuntimes.values()]
+        .sort((left, right) => {
+          const ts = String(right.updated_at || '').localeCompare(String(left.updated_at || ''));
+          if (ts !== 0) return ts;
+          return String(left.thread_id || '').localeCompare(String(right.thread_id || ''));
+        })
+        .slice(0, 3)
+        .map((threadRuntime) => ({
+          thread_id: threadRuntime.thread_id,
+          root_message_id: threadRuntime.root_message_id,
+          updated_at: threadRuntime.updated_at,
+        }));
+      resolved.push({
+        reference: ref.reference,
+        kind: 'channel',
+        channel_id: channel.record_id,
+        channel_title: channel.title ?? '',
+        participants: normalizeChannelParticipants(channel),
+        updated_at: channel.updated_at ?? '',
+        recent_threads: threads,
+      });
+    }
+  }
+  return resolved;
+}
+
+function buildDeepThreadSearchResults(matches = [], limit = 5) {
+  const byThread = new Map();
+  for (const item of matches) {
+    const key = item.threadRuntime.key;
+    const existing = byThread.get(key) ?? {
+      threadRuntime: item.threadRuntime,
+      scopeRank: item.score.scopeRank,
+      exactMatches: 0,
+      tokenMatchCount: 0,
+      updated_at: '',
+      matchingMessages: [],
+    };
+    existing.scopeRank = Math.min(existing.scopeRank, item.score.scopeRank);
+    existing.exactMatches = Math.max(existing.exactMatches, item.score.exactMatches);
+    existing.tokenMatchCount = Math.max(existing.tokenMatchCount, item.score.tokenMatches.length);
+    existing.updated_at = maxIsoTimestamp(existing.updated_at, item.message.updated_at ?? '');
+    existing.matchingMessages.push({
+      message_id: item.message.record_id,
+      sender_npub: item.message.sender_npub ?? null,
+      body: item.message.body ?? '',
+      updated_at: item.message.updated_at ?? '',
+      token_match_count: item.score.tokenMatches.length,
+      exact_match: item.score.exactMatches === 1,
+    });
+    byThread.set(key, existing);
+  }
+
+  return [...byThread.values()]
+    .sort((left, right) => {
+      if (right.exactMatches !== left.exactMatches) return right.exactMatches - left.exactMatches;
+      if (right.tokenMatchCount !== left.tokenMatchCount) return right.tokenMatchCount - left.tokenMatchCount;
+      if (left.scopeRank !== right.scopeRank) return left.scopeRank - right.scopeRank;
+      const ts = String(right.updated_at || '').localeCompare(String(left.updated_at || ''));
+      if (ts !== 0) return ts;
+      return String(left.threadRuntime.key || '').localeCompare(String(right.threadRuntime.key || ''));
+    })
+    .slice(0, limit)
+    .map((entry) => ({
+      ...formatThreadSummary(entry.threadRuntime),
+      scope: entry.scopeRank === 0 ? 'current_thread' : entry.scopeRank === 1 ? 'same_channel' : 'other_channel',
+      matching_messages: entry.matchingMessages
+        .sort((left, right) => {
+          if (right.exact_match !== left.exact_match) return Number(right.exact_match) - Number(left.exact_match);
+          if (right.token_match_count !== left.token_match_count) return right.token_match_count - left.token_match_count;
+          const ts = String(right.updated_at || '').localeCompare(String(left.updated_at || ''));
+          if (ts !== 0) return ts;
+          return String(left.message_id || '').localeCompare(String(right.message_id || ''));
+        })
+        .slice(0, 2)
+        .map(({ message_id, sender_npub, body, updated_at }) => ({
+          message_id,
+          sender_npub,
+          body,
+          updated_at,
+        })),
+    }));
+}
+
+function buildRelatedSupportingMessages(threadRuntime, sharedTerms = [], limit = 2) {
+  if (!Array.isArray(sharedTerms) || sharedTerms.length === 0) return [];
+  return threadRuntime.messages
+    .map((message) => {
+      const body = String(message.body || '').toLowerCase();
+      const matchCount = sharedTerms.filter((term) => body.includes(term)).length;
+      if (matchCount === 0) return null;
+      return {
+        message_id: message.record_id,
+        sender_npub: message.sender_npub ?? null,
+        body: message.body ?? '',
+        updated_at: message.updated_at ?? '',
+        matchCount,
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => {
+      if (right.matchCount !== left.matchCount) return right.matchCount - left.matchCount;
+      const ts = String(right.updated_at || '').localeCompare(String(left.updated_at || ''));
+      if (ts !== 0) return ts;
+      return String(left.message_id || '').localeCompare(String(right.message_id || ''));
+    })
+    .slice(0, limit)
+    .map(({ message_id, sender_npub, body, updated_at }) => ({
+      message_id,
+      sender_npub,
+      body,
+      updated_at,
+    }));
+}
+
+function resolveContextFromChannelRuntime(channelRuntime, base = {}) {
+  const storedThread = base.thread_id ? channelRuntime.threads.get(base.thread_id) : null;
+  const threadMessages = storedThread && storedThread.length > 0
+    ? storedThread
+    : [...channelRuntime.threads.values()]
+      .filter((messages) => messages.length > 0)
+      .sort((left, right) => {
+        const leftLatest = latestThreadMessage(left);
+        const rightLatest = latestThreadMessage(right);
+        const ts = String(rightLatest?.updated_at || '').localeCompare(String(leftLatest?.updated_at || ''));
+        if (ts !== 0) return ts;
+        return String(leftLatest?.record_id || '').localeCompare(String(rightLatest?.record_id || ''));
+      })[0] ?? null;
+
+  if (!threadMessages || threadMessages.length === 0) {
+    throw new Error(`No local thread context available for channel ${channelRuntime.channel.record_id}.`);
+  }
+
+  const lastMessage = base.message_id
+    ? channelRuntime.byId.get(base.message_id) ?? latestThreadMessage(threadMessages)
+    : latestThreadMessage(threadMessages);
+  if (!lastMessage) {
+    throw new Error(`Thread ${threadMessages[0]?.thread_id ?? '<unknown>'} has no local messages.`);
+  }
+
+  return {
+    channel_id: channelRuntime.channel.record_id,
+    thread_id: threadMessages[0].thread_id,
+    message_id: lastMessage.record_id,
+  };
+}
+
+export function resolveChatRuntimeContext(db, options = {}) {
+  const explicit = {
+    channel_id: String(options.channelId || options.channel_id || '').trim() || null,
+    thread_id: String(options.threadId || options.thread_id || '').trim() || null,
+    message_id: String(options.messageId || options.message_id || '').trim() || null,
+  };
+
+  let resolved = null;
+  if (explicit.message_id) {
+    const messageRow = getRow(
+      db,
+      `SELECT * FROM messages WHERE record_id = ? AND record_state != 'deleted'`,
+      [explicit.message_id],
+    );
+    if (!messageRow) throw new Error(`Chat message not found locally: ${explicit.message_id}`);
+    const message = parseMessageRow(messageRow);
+    const channelRuntime = buildChannelRuntime(db, message.channel_id);
+    const indexed = channelRuntime.byId.get(message.record_id);
+    if (!indexed) throw new Error(`Chat message not found in local channel mirror: ${explicit.message_id}`);
+    if (explicit.channel_id && explicit.channel_id !== indexed.channel_id) {
+      throw new Error(`Chat message ${indexed.record_id} is in channel ${indexed.channel_id}, not ${explicit.channel_id}.`);
+    }
+    resolved = {
+      channel_id: indexed.channel_id,
+      thread_id: indexed.thread_id,
+      message_id: indexed.record_id,
+    };
+  } else if (explicit.thread_id) {
+    const rootRow = getRow(
+      db,
+      `SELECT * FROM messages WHERE record_id = ? AND record_state != 'deleted'`,
+      [explicit.thread_id],
+    );
+    if (!rootRow) throw new Error(`Chat thread not found locally: ${explicit.thread_id}`);
+    const root = parseMessageRow(rootRow);
+    if (root.parent_message_id) {
+      throw new Error(`Thread id must reference a root message: ${explicit.thread_id}`);
+    }
+    if (explicit.channel_id && explicit.channel_id !== root.channel_id) {
+      throw new Error(`Chat thread ${explicit.thread_id} is in channel ${root.channel_id}, not ${explicit.channel_id}.`);
+    }
+    const channelRuntime = buildChannelRuntime(db, root.channel_id);
+    resolved = resolveContextFromChannelRuntime(channelRuntime, {
+      thread_id: explicit.thread_id,
+    });
+  } else if (explicit.channel_id) {
+    const channelRuntime = buildChannelRuntime(db, explicit.channel_id);
+    resolved = resolveContextFromChannelRuntime(channelRuntime);
+  } else {
+    resolved = getStoredRuntimeContext(db);
+    if (!resolved?.channel_id || !resolved?.thread_id) {
+      throw new Error('No local chat context available. Provide --channel, --thread, or --message first.');
+    }
+    const channelRuntime = buildChannelRuntime(db, resolved.channel_id);
+    resolved = resolveContextFromChannelRuntime(channelRuntime, resolved);
+  }
+
+  setStoredRuntimeContext(db, resolved);
+  return resolved;
+}
+
+export function buildChatContextPayload(db, options = {}) {
+  const context = resolveChatRuntimeContext(db, options);
+  const limit = clampLimit(options.limit, 6, 20);
+  const channelRuntime = buildChannelRuntime(db, context.channel_id);
+  const threadMessages = channelRuntime.threads.get(context.thread_id) ?? [];
+  if (threadMessages.length === 0) {
+    throw new Error(`Thread not found locally: ${context.thread_id}`);
+  }
+  const recentMessages = threadMessages.slice(-limit).map(formatMessage);
+  return {
+    channel_id: context.channel_id,
+    thread_id: context.thread_id,
+    participants: normalizeChannelParticipants(channelRuntime.channel),
+    recent_messages: recentMessages,
+  };
+}
+
+export function buildChatHistoryPayload(db, options = {}) {
+  const context = resolveChatRuntimeContext(db, options);
+  const limit = clampLimit(options.limit, 20, 50);
+  const offset = parseCursor(options.cursor);
+  const channelRuntime = buildChannelRuntime(db, context.channel_id);
+  const threadMessages = channelRuntime.threads.get(context.thread_id) ?? [];
+  if (threadMessages.length === 0) {
+    throw new Error(`Thread not found locally: ${context.thread_id}`);
+  }
+
+  const newestFirst = [...threadMessages].reverse();
+  const page = newestFirst.slice(offset, offset + limit).reverse();
+  const nextOffset = offset + limit;
+
+  return {
+    channel_id: context.channel_id,
+    thread_id: context.thread_id,
+    messages: page.map(formatMessage),
+    cursor: nextOffset < newestFirst.length ? encodeCursor(nextOffset) : null,
+  };
+}
+
+export function buildChatSearchPayload(db, options = {}) {
+  const query = String(options.query || '').trim();
+  if (!query) throw new Error('Search query is required.');
+  const context = resolveChatRuntimeContext(db, options);
+  const limit = clampLimit(options.limit, 10, 25);
+  const workspaceRuntime = buildWorkspaceRuntime(db);
+  const queryLower = query.toLowerCase();
+  const queryTokens = tokenizeText(query);
+  const deep = options.deep === true;
+  const referenceMatches = resolveStructuredReferences(db, workspaceRuntime, options.references ?? options.reference ?? []);
+
+  const messageMatches = workspaceRuntime.messages
+    .map((message) => {
+      const threadRuntime = workspaceRuntime.threadsByKey.get(threadKey(message.channel_id, message.thread_id));
+      if (!threadRuntime) return null;
+      const score = searchScoreForMessage(message, threadRuntime, context, queryLower, queryTokens);
+      if (!score) return null;
+      return { message, threadRuntime, score };
+    })
+    .filter(Boolean)
+    .sort((left, right) => {
+      if (right.score.exactMatches !== left.score.exactMatches) return right.score.exactMatches - left.score.exactMatches;
+      if (right.score.tokenMatches.length !== left.score.tokenMatches.length) {
+        return right.score.tokenMatches.length - left.score.tokenMatches.length;
+      }
+      if (left.score.scopeRank !== right.score.scopeRank) return left.score.scopeRank - right.score.scopeRank;
+      const ts = String(right.message.updated_at || '').localeCompare(String(left.message.updated_at || ''));
+      if (ts !== 0) return ts;
+      const channel = String(left.message.channel_id || '').localeCompare(String(right.message.channel_id || ''));
+      if (channel !== 0) return channel;
+      return String(left.message.record_id || '').localeCompare(String(right.message.record_id || ''));
+    })
+    .slice(0, limit);
+
+  const results = messageMatches
+    .map(({ message, threadRuntime, score }) => ({
+      message_id: message.record_id,
+      channel_id: message.channel_id,
+      channel_title: threadRuntime.channel_title,
+      thread_id: message.thread_id,
+      parent_message_id: message.parent_message_id ?? null,
+      sender_npub: message.sender_npub ?? null,
+      body: message.body ?? '',
+      updated_at: message.updated_at ?? '',
+      scope: score.scope,
+    }));
+
+  return {
+    query,
+    references: referenceMatches,
+    results,
+    ...(deep ? { threads: buildDeepThreadSearchResults(messageMatches, Math.min(limit, 5)) } : {}),
+  };
+}
+
+export function buildChatRelatedPayload(db, options = {}) {
+  const context = resolveChatRuntimeContext(db, options);
+  const limit = clampLimit(options.limit, 5, 10);
+  const workspaceRuntime = buildWorkspaceRuntime(db);
+  const currentThread = workspaceRuntime.threadsByKey.get(threadKey(context.channel_id, context.thread_id));
+  const deep = options.deep === true;
+  if (!currentThread) {
+    throw new Error(`Thread not found locally: ${context.thread_id}`);
+  }
+
+  const relatedThreads = [...workspaceRuntime.threadsByKey.values()]
+    .filter((threadRuntime) => threadRuntime.key !== currentThread.key && threadRuntime.message_count > 0)
+    .map((threadRuntime) => {
+      const relation = relatedScoreForThread(threadRuntime, currentThread);
+      if (!relation) return null;
+      return {
+        channel_id: threadRuntime.channel_id,
+        channel_title: threadRuntime.channel_title,
+        thread_id: threadRuntime.thread_id,
+        root_message_id: threadRuntime.root_message_id,
+        last_message_id: threadRuntime.last_message_id,
+        message_count: threadRuntime.message_count,
+        updated_at: threadRuntime.updated_at,
+        summary: threadRuntime.summary,
+        participants: threadRuntime.participants,
+        match_score: relation.matchScore,
+        relation: {
+          same_channel: relation.sameChannel,
+          shared_terms: relation.sharedTerms,
+          shared_participants: relation.sharedParticipants,
+        },
+        ...(deep ? { matching_messages: buildRelatedSupportingMessages(threadRuntime, relation.sharedTerms, 2) } : {}),
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => {
+      if (right.match_score !== left.match_score) return right.match_score - left.match_score;
+      if (left.relation.same_channel !== right.relation.same_channel) {
+        return Number(right.relation.same_channel) - Number(left.relation.same_channel);
+      }
+      const ts = String(right.updated_at || '').localeCompare(String(left.updated_at || ''));
+      if (ts !== 0) return ts;
+      const channel = String(left.channel_id || '').localeCompare(String(right.channel_id || ''));
+      if (channel !== 0) return channel;
+      return String(left.thread_id || '').localeCompare(String(right.thread_id || ''));
+    })
+    .slice(0, limit);
+
+  return {
+    message_id: context.message_id,
+    related_threads: relatedThreads,
+  };
+}
+
+export async function sendChatReplyCurrent(db, options = {}) {
+  const body = String(options.body || '').trim();
+  if (!body) throw new Error('Reply body is required.');
+  if (typeof options.sendReply !== 'function') {
+    throw new Error('sendReply callback is required.');
+  }
+
+  const context = resolveChatRuntimeContext(db, options);
+  const channelRuntime = buildChannelRuntime(db, context.channel_id);
+  const threadMessages = channelRuntime.threads.get(context.thread_id) ?? [];
+  if (threadMessages.length === 0) {
+    throw new Error(`Reply target thread not found locally: ${context.thread_id}`);
+  }
+
+  const response = await options.sendReply({
+    channel_id: context.channel_id,
+    thread_id: context.thread_id,
+    body,
+    channel: channelRuntime.channel,
+  });
+  const messageId = String(response?.message_id || '').trim();
+  if (!messageId) throw new Error('Reply sender did not return message_id.');
+
+  const nextContext = {
+    channel_id: context.channel_id,
+    thread_id: context.thread_id,
+    message_id: messageId,
+  };
+  setStoredRuntimeContext(db, nextContext);
+
+  return {
+    channel_id: context.channel_id,
+    thread_id: context.thread_id,
+    message_id: messageId,
+    status: 'sent',
+  };
+}
+
+export {
+  CHAT_RUNTIME_CONTEXT_META_KEY,
+  getStoredRuntimeContext,
+  setStoredRuntimeContext,
+};