@bbigbang/core 0.1.0

package/dist/web/conversationSummaries.js

@@ -0,0 +1,876 @@
+import { buildThreadShortId, } from '@bbigbang/protocol';
+import { collectAgentSelfState } from './agentSelfState.js';
+import { getThreadCollaborationSummary } from './threadTaskBindings.js';
+import { getLatestConversationHandoffForConversation } from './conversationHandoffs.js';
+import { listUnifiedRecentSurfaceParticipants } from './collaborationSurfaceState.js';
+import { TARGET_PARTICIPANT_ACTIVE_WINDOW_MS } from './targetParticipants.js';
+import { TASK_LIFECYCLE_SOURCE } from './taskLifecycleMessages.js';
+export function refreshConversationSummariesForAgent(db, agent, options) {
+    const state = collectAgentSelfState(db, agent);
+    const filtered = options?.status && options.status !== 'all'
+        ? state.conversations.filter((conversation) => conversation.status === options.status)
+        : state.conversations;
+    return filtered.map((conversation) => upsertConversationSummary(db, agent, conversation));
+}
+export function refreshConversationSummary(db, agent, conversationId) {
+    const state = collectAgentSelfState(db, agent, { conversationId });
+    const conversation = state.conversations.find((item) => item.conversationId === conversationId);
+    if (!conversation)
+        return null;
+    return upsertConversationSummary(db, agent, conversation);
+}
+export function listConversationSummariesForAgent(db, agent, options) {
+    const state = collectAgentSelfState(db, agent);
+    const filtered = options?.status && options.status !== 'all'
+        ? state.conversations.filter((conversation) => conversation.status === options.status)
+        : state.conversations;
+    return filtered.map((conversation) => getConversationSummaryRecord(db, agent, conversation));
+}
+export function getConversationSummary(db, agent, conversationId) {
+    const state = collectAgentSelfState(db, agent, { conversationId });
+    const conversation = state.conversations.find((item) => item.conversationId === conversationId);
+    if (!conversation)
+        return null;
+    return getConversationSummaryRecord(db, agent, conversation);
+}
+export function buildConversationSummaryRecords(db, agent, conversations) {
+    return conversations.map((conversation) => getConversationSummaryRecord(db, agent, conversation));
+}
+export function buildConversationSurfaceResponse(record, options) {
+    const contextKey = options?.contextKey ?? 'context';
+    const summary = options?.context ?? record.summary;
+    const response = {
+        conversationId: record.conversationId,
+        replyTarget: record.replyTarget,
+        status: record.status,
+        surfaceKind: record.surfaceKind,
+        threadKind: record.threadKind,
+        threadRootId: record.threadRootId,
+        unreadCount: record.unreadCount,
+        queuedPromptCount: record.queuedPromptCount,
+        hasActiveRun: record.hasActiveRun,
+        updatedAt: record.updatedAt,
+        summaryUpdatedAt: record.summaryUpdatedAt,
+        summaryText: formatConversationSummaryText(record.replyTarget, record.status, summary),
+        ...(contextKey === 'summary' ? { summary } : { context: summary }),
+    };
+    if (options?.includeReportText) {
+        response.reportText = formatConversationSummary({
+            ...record,
+            summary,
+        });
+    }
+    return response;
+}
+export function refreshConversationSummariesForConversationIds(db, lookupAgent, conversationIds) {
+    const refreshed = [];
+    const seen = new Set();
+    for (const conversationId of conversationIds) {
+        if (!conversationId || seen.has(conversationId))
+            continue;
+        seen.add(conversationId);
+        const row = db.prepare(`SELECT agent_id as agentId
+         FROM conversations
+        WHERE id = ?
+        LIMIT 1`).get(conversationId);
+        if (!row?.agentId)
+            continue;
+        const agent = lookupAgent(row.agentId);
+        if (!agent)
+            continue;
+        const summary = refreshConversationSummary(db, agent, conversationId);
+        if (summary)
+            refreshed.push(summary);
+    }
+    return refreshed;
+}
+export function refreshConversationSummariesForMessageScope(db, lookupAgent, params) {
+    return refreshConversationSummariesForConversationIds(db, lookupAgent, listConversationIdsForMessageScope(db, params));
+}
+export function refreshConversationSummariesForTask(db, lookupAgent, taskId) {
+    const row = db.prepare(`SELECT t.channel_id as channelId,
+            t.message_id as messageId,
+            COALESCE(t.dm_target, cm.target) as replyTarget
+       FROM tasks t
+       LEFT JOIN channel_messages cm ON cm.message_id = t.message_id
+      WHERE t.task_id = ?
+      LIMIT 1`).get(taskId);
+    if (!row)
+        return [];
+    const conversationIds = new Set();
+    for (const conversationId of listConversationIdsForMessageScope(db, {
+        channelId: row.channelId,
+        replyTarget: row.replyTarget,
+        threadRootId: null,
+    })) {
+        conversationIds.add(conversationId);
+    }
+    if (row.messageId) {
+        for (const conversationId of listConversationIdsForMessageScope(db, {
+            channelId: row.channelId,
+            threadRootId: buildThreadShortId(row.messageId),
+        })) {
+            conversationIds.add(conversationId);
+        }
+    }
+    return refreshConversationSummariesForConversationIds(db, lookupAgent, conversationIds);
+}
+export function getStoredConversationSummary(db, conversationId) {
+    const row = db.prepare(`SELECT conversation_id as conversationId,
+            agent_id as agentId,
+            reply_target as replyTarget,
+            channel_id as channelId,
+            thread_kind as threadKind,
+            thread_root_id as threadRootId,
+            summary_json as summaryJson,
+            last_message_id as lastMessageId,
+            last_message_seq as lastMessageSeq,
+            updated_at as updatedAt
+       FROM conversation_summaries
+      WHERE conversation_id = ?
+      LIMIT 1`).get(conversationId);
+    if (!row)
+        return null;
+    return {
+        conversationId: row.conversationId,
+        agentId: row.agentId,
+        replyTarget: row.replyTarget,
+        channelId: row.channelId,
+        threadKind: row.threadKind,
+        threadRootId: row.threadRootId ?? null,
+        summary: parseConversationSummaryPayload(row.summaryJson),
+        lastMessageId: row.lastMessageId ?? null,
+        lastMessageSeq: row.lastMessageSeq ?? null,
+        updatedAt: new Date(row.updatedAt).toISOString(),
+    };
+}
+export function formatConversationSummary(record, options) {
+    const includeGoal = options?.includeGoal ?? true;
+    const includeRecentState = options?.includeRecentState ?? true;
+    const includeLinkedTasks = options?.includeLinkedTasks ?? true;
+    const includeLastMessage = options?.includeLastMessage ?? true;
+    const lines = [
+        `Target: ${record.replyTarget}`,
+        `Status: ${record.status}`,
+        `Surface: ${record.surfaceKind}`,
+        `Unread: ${record.unreadCount}`,
+        `Queued prompts: ${record.queuedPromptCount}`,
+    ];
+    if (includeGoal && record.summary.goal)
+        lines.push(`Goal: ${record.summary.goal}`);
+    if (includeRecentState && record.summary.recentState)
+        lines.push(`Recent state: ${record.summary.recentState}`);
+    if (record.summary.blockers.length > 0)
+        lines.push(`Blockers: ${record.summary.blockers.join('; ')}`);
+    if (record.summary.nextStep)
+        lines.push(`Next: ${record.summary.nextStep}`);
+    if (record.summary.myRole)
+        lines.push(`My role: ${record.summary.myRole}`);
+    if (record.summary.ownerName)
+        lines.push(`Owner: @${record.summary.ownerName}`);
+    if (includeLinkedTasks && record.summary.linkedTaskRefs.length > 0) {
+        lines.push(`Linked tasks: ${record.summary.linkedTaskRefs.join(', ')}`);
+    }
+    if (record.summary.boundTask) {
+        lines.push(`Bound task: ${formatTaskRef(record.summary.boundTask.agentTaskRef, record.summary.boundTask.taskNumber)} [${record.summary.boundTask.status}]`);
+    }
+    if (record.summary.participants.length > 0) {
+        lines.push(`Participants: ${record.summary.participants.map((name) => `@${name}`).join(', ')}`);
+    }
+    if (record.summary.activeHandoff) {
+        lines.push(`Active handoff: ${record.summary.activeHandoff.mode} [${record.summary.activeHandoff.status}] -> ${record.summary.activeHandoff.targetReplyTarget}`);
+    }
+    if (includeLastMessage && record.summary.lastMessage) {
+        lines.push(`Last message: @${record.summary.lastMessage.senderName} — ${record.summary.lastMessage.preview}`);
+    }
+    return lines.join('\n');
+}
+function getConversationSummaryRecord(db, agent, conversation) {
+    const stored = getStoredConversationSummary(db, conversation.conversationId);
+    if (stored && isStoredConversationSummaryFresh(db, agent.agentId, conversation, stored)) {
+        return buildConversationSummaryRecordFromStored(conversation, stored);
+    }
+    return upsertConversationSummary(db, agent, conversation);
+}
+function isStoredConversationSummaryFresh(db, agentId, conversation, stored) {
+    if (!stored)
+        return false;
+    if (stored.agentId !== agentId)
+        return false;
+    if (stored.replyTarget !== conversation.replyTarget)
+        return false;
+    if (stored.channelId !== conversation.channelId)
+        return false;
+    if (stored.threadKind !== conversation.threadKind)
+        return false;
+    if ((stored.threadRootId ?? null) !== (conversation.threadRootId ?? null))
+        return false;
+    if (stored.summary.unreadCount !== conversation.unreadCount)
+        return false;
+    if (stored.summary.queuedPromptCount !== conversation.queuedPromptCount)
+        return false;
+    const storedUpdatedAt = Date.parse(stored.updatedAt);
+    const conversationUpdatedAt = Date.parse(conversation.updatedAt);
+    if (Number.isFinite(storedUpdatedAt) && Number.isFinite(conversationUpdatedAt) && conversationUpdatedAt > storedUpdatedAt) {
+        return false;
+    }
+    if (Number.isFinite(storedUpdatedAt) && (Date.now() - storedUpdatedAt) >= TARGET_PARTICIPANT_ACTIVE_WINDOW_MS) {
+        return false;
+    }
+    const latestOpenHandoff = getLatestConversationHandoffForConversation(db, {
+        conversationId: conversation.conversationId,
+        openOnly: true,
+    });
+    if ((stored.summary.activeHandoff?.updatedAt ?? null) !== (latestOpenHandoff?.updatedAt ?? null)) {
+        return false;
+    }
+    const collaborationState = loadConversationCollaborationState(db, conversation);
+    if ((stored.summary.ownerAgentId ?? null) !== collaborationState.ownerAgentId) {
+        return false;
+    }
+    if ((stored.summary.ownerName ?? null) !== collaborationState.ownerName) {
+        return false;
+    }
+    if (!equalStringArrays(stored.summary.participants, collaborationState.participants)) {
+        return false;
+    }
+    const latestMessage = loadLatestScopeMessage(db, conversation);
+    return (stored.lastMessageId ?? null) === (latestMessage?.messageId ?? null)
+        && (stored.lastMessageSeq ?? null) === (latestMessage?.seq ?? null);
+}
+function buildConversationSummaryRecordFromStored(conversation, stored) {
+    const summary = {
+        ...stored.summary,
+        unreadCount: conversation.unreadCount,
+        queuedPromptCount: conversation.queuedPromptCount,
+    };
+    return {
+        conversationId: conversation.conversationId,
+        replyTarget: conversation.replyTarget,
+        status: conversation.status,
+        surfaceKind: conversation.surfaceKind,
+        threadKind: conversation.threadKind,
+        threadRootId: conversation.threadRootId,
+        unreadCount: conversation.unreadCount,
+        queuedPromptCount: conversation.queuedPromptCount,
+        hasActiveRun: conversation.hasActiveRun,
+        updatedAt: conversation.updatedAt,
+        summaryUpdatedAt: stored.updatedAt,
+        summary,
+        summaryText: formatConversationSummaryText(conversation.replyTarget, conversation.status, summary),
+    };
+}
+function listConversationIdsForMessageScope(db, params) {
+    const threadRootId = normalizeOptionalText(params.threadRootId);
+    if (params.channelId.startsWith('dm:')) {
+        if (threadRootId) {
+            const rows = db.prepare(`SELECT id
+           FROM conversations
+          WHERE channel_id = ?
+            AND thread_kind = 'direct'
+            AND thread_root_id = ?
+          ORDER BY updated_at DESC, created_at DESC`).all(params.channelId, threadRootId);
+            return rows.map((row) => row.id);
+        }
+        const replyTarget = normalizeOptionalText(params.replyTarget);
+        if (!replyTarget)
+            return [];
+        const rows = db.prepare(`SELECT id
+         FROM conversations
+        WHERE channel_id = ?
+          AND thread_kind = 'direct'
+          AND thread_root_id IS NULL
+          AND reply_target = ?
+        ORDER BY updated_at DESC, created_at DESC`).all(params.channelId, replyTarget);
+        return rows.map((row) => row.id);
+    }
+    if (threadRootId) {
+        const rows = db.prepare(`SELECT id
+         FROM conversations
+        WHERE channel_id = ?
+          AND thread_kind = 'branch'
+          AND thread_root_id = ?
+        ORDER BY updated_at DESC, created_at DESC`).all(params.channelId, threadRootId);
+        return rows.map((row) => row.id);
+    }
+    const rows = db.prepare(`SELECT id
+       FROM conversations
+      WHERE channel_id = ?
+        AND thread_kind = 'branch'
+        AND thread_root_id IS NULL
+      ORDER BY updated_at DESC, created_at DESC`).all(params.channelId);
+    return rows.map((row) => row.id);
+}
+function upsertConversationSummary(db, agent, conversation) {
+    const messages = loadScopeMessages(db, conversation);
+    const latestMessage = messages.at(-1) ?? null;
+    const lastUserMessage = [...messages].reverse().find((message) => message.senderType === 'user') ?? null;
+    const lastAgentMessage = [...messages].reverse().find((message) => message.senderType === 'agent') ?? null;
+    const lastSystemMessage = [...messages].reverse().find((message) => message.senderType === 'system') ?? null;
+    const linkedTasks = loadLinkedTasks(db, conversation);
+    const linkedTaskSummaries = linkedTasks.map(toLinkedTaskSummary);
+    const lastRunError = loadLastRunError(db, conversation.conversationId);
+    const collaborationState = loadConversationCollaborationState(db, conversation);
+    const { threadCollaboration } = collaborationState;
+    const targetParticipants = collaborationState.participants;
+    const ownerAgentId = collaborationState.ownerAgentId;
+    const ownerName = collaborationState.ownerName;
+    const boundTask = threadCollaboration.boundTask
+        ? (() => {
+            const linkedTask = linkedTasks[0] ?? {
+                taskId: threadCollaboration.boundTask.taskId,
+                agentTaskRef: null,
+                taskNumber: threadCollaboration.boundTask.taskNumber,
+                title: threadCollaboration.boundTask.title,
+                status: threadCollaboration.boundTask.status,
+                claimedByName: threadCollaboration.boundTask.assigneeName ?? null,
+                description: threadCollaboration.boundTask.description ?? null,
+                messageId: null,
+                channelId: threadCollaboration.boundTask.channelId,
+                sourceTarget: conversation.replyTarget,
+            };
+            const summary = toLinkedTaskSummary(linkedTask);
+            return {
+                ...summary,
+                threadTarget: summary.threadTarget ?? conversation.replyTarget,
+                description: threadCollaboration.boundTask.description ?? null,
+                claimedByName: threadCollaboration.boundTask.assigneeName ?? null,
+            };
+        })()
+        : null;
+    const activeHandoff = toActiveHandoffSummary(getLatestConversationHandoffForConversation(db, {
+        conversationId: conversation.conversationId,
+        openOnly: true,
+    }));
+    const blockers = [];
+    if (conversation.status === 'awaiting_approval')
+        blockers.push('Awaiting human approval');
+    if (conversation.status === 'failed')
+        blockers.push(lastRunError ? `Last run failed: ${lastRunError}` : 'Last run failed');
+    if (conversation.queuedPromptCount > 0 && conversation.status !== 'active' && conversation.status !== 'recovering') {
+        blockers.push(`${conversation.queuedPromptCount} queued prompt(s) pending`);
+    }
+    if (activeHandoff?.status === 'started' || activeHandoff?.status === 'accepted') {
+        blockers.push(`Handoff in progress to ${activeHandoff.targetReplyTarget}`);
+    }
+    const taskSummary = linkedTasks[0] ?? null;
+    const goal = taskSummary
+        ? summarizeText(taskSummary.title, 160)
+        : summarizeText(lastUserMessage?.content ?? loadThreadRootMessageContent(db, conversation) ?? null, 160);
+    const recentState = summarizeText(lastAgentMessage?.content ?? lastSystemMessage?.content ?? null, 180);
+    const nextStep = buildNextStep({
+        conversation,
+        lastUserMessage: lastUserMessage?.content ?? null,
+        linkedTask: taskSummary,
+    });
+    const linkedTaskRefs = linkedTasks.map((task) => formatTaskRef(task.agentTaskRef, task.taskNumber));
+    const linkedTaskTitles = linkedTasks.map((task) => summarizeText(task.title, 160)).filter((title) => Boolean(title));
+    const myRole = deriveMyRole({
+        agent,
+        conversation,
+        boundTask,
+        ownerAgentId,
+        ownerName,
+        participants: targetParticipants,
+    });
+    const summary = {
+        goal,
+        recentState,
+        blockers,
+        nextStep,
+        lastUserMessage: summarizeText(lastUserMessage?.content ?? null, 180),
+        lastAgentMessage: summarizeText(lastAgentMessage?.content ?? null, 180),
+        linkedTaskRefs,
+        linkedTaskTitles,
+        unreadCount: conversation.unreadCount,
+        queuedPromptCount: conversation.queuedPromptCount,
+        lastMessageAt: latestMessage ? new Date(latestMessage.createdAt).toISOString() : null,
+        lastMessage: latestMessage
+            ? {
+                messageId: latestMessage.messageId,
+                target: latestMessage.target,
+                senderName: latestMessage.senderName,
+                senderType: latestMessage.senderType,
+                preview: summarizeText(latestMessage.content, 180) ?? '',
+                createdAt: new Date(latestMessage.createdAt).toISOString(),
+            }
+            : null,
+        linkedTasks: linkedTaskSummaries,
+        boundTask,
+        ownerAgentId,
+        ownerName,
+        participants: targetParticipants,
+        myRole,
+        activeHandoff,
+    };
+    const now = Date.now();
+    db.prepare(`INSERT INTO conversation_summaries(
+       conversation_id,
+       agent_id,
+       reply_target,
+       channel_id,
+       thread_kind,
+       thread_root_id,
+       summary_json,
+       last_message_id,
+       last_message_seq,
+       updated_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(conversation_id) DO UPDATE SET
+       agent_id = excluded.agent_id,
+       reply_target = excluded.reply_target,
+       channel_id = excluded.channel_id,
+       thread_kind = excluded.thread_kind,
+       thread_root_id = excluded.thread_root_id,
+       summary_json = excluded.summary_json,
+       last_message_id = excluded.last_message_id,
+       last_message_seq = excluded.last_message_seq,
+       updated_at = excluded.updated_at`).run(conversation.conversationId, agent.agentId, conversation.replyTarget, conversation.channelId, conversation.threadKind, conversation.threadRootId, JSON.stringify(summary), latestMessage?.messageId ?? null, latestMessage?.seq ?? null, now);
+    return {
+        conversationId: conversation.conversationId,
+        replyTarget: conversation.replyTarget,
+        status: conversation.status,
+        surfaceKind: conversation.surfaceKind,
+        threadKind: conversation.threadKind,
+        threadRootId: conversation.threadRootId,
+        unreadCount: conversation.unreadCount,
+        queuedPromptCount: conversation.queuedPromptCount,
+        hasActiveRun: conversation.hasActiveRun,
+        updatedAt: conversation.updatedAt,
+        summaryUpdatedAt: new Date(now).toISOString(),
+        summary,
+        summaryText: formatConversationSummaryText(conversation.replyTarget, conversation.status, summary),
+    };
+}
+function loadConversationCollaborationState(db, conversation) {
+    const threadCollaboration = getThreadCollaborationSummary(db, {
+        channelId: conversation.channelId,
+        threadRootId: conversation.threadRootId,
+    });
+    const participants = conversation.threadRootId
+        ? threadCollaboration.participants
+        : listUnifiedRecentSurfaceParticipants(db, {
+            channelId: conversation.channelId,
+            threadRootId: conversation.threadRootId,
+        }).map((participant) => participant.name);
+    return {
+        threadCollaboration,
+        ownerAgentId: threadCollaboration.ownerAgentId ?? null,
+        ownerName: threadCollaboration.ownerName ?? null,
+        participants,
+    };
+}
+function equalStringArrays(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((value, index) => value === right[index]);
+}
+function loadScopeMessages(db, conversation, limit = 12) {
+    if (conversation.threadRootId) {
+        if (conversation.replyTarget.startsWith('dm:@')) {
+            return db.prepare(`SELECT message_id as messageId,
+                sender_name as senderName,
+                sender_type as senderType,
+                target,
+                content,
+                seq,
+                created_at as createdAt
+           FROM channel_messages
+          WHERE channel_id = ?
+            AND COALESCE(message_source, '') != ?
+            AND (
+              thread_root_id = ?
+              OR (thread_root_id IS NULL AND target = ?)
+            )
+          ORDER BY seq DESC
+          LIMIT ?`).all(conversation.channelId, TASK_LIFECYCLE_SOURCE, conversation.threadRootId, conversation.replyTarget, limit)
+                .reverse();
+        }
+        return db.prepare(`SELECT message_id as messageId,
+              sender_name as senderName,
+              sender_type as senderType,
+              target,
+              content,
+              seq,
+              created_at as createdAt
+        FROM channel_messages
+        WHERE channel_id = ?
+          AND COALESCE(message_source, '') != ?
+          AND thread_root_id = ?
+        ORDER BY seq DESC
+        LIMIT ?`).all(conversation.channelId, TASK_LIFECYCLE_SOURCE, conversation.threadRootId, limit)
+            .reverse();
+    }
+    if (conversation.replyTarget.startsWith('dm:@')) {
+        return db.prepare(`SELECT message_id as messageId,
+              sender_name as senderName,
+              sender_type as senderType,
+              target,
+              content,
+              seq,
+              created_at as createdAt
+        FROM channel_messages
+        WHERE channel_id = ?
+          AND COALESCE(message_source, '') != ?
+          AND thread_root_id IS NULL
+          AND target = ?
+        ORDER BY seq DESC
+        LIMIT ?`).all(conversation.channelId, TASK_LIFECYCLE_SOURCE, conversation.replyTarget, limit)
+            .reverse();
+    }
+    return db.prepare(`SELECT message_id as messageId,
+            sender_name as senderName,
+            sender_type as senderType,
+            target,
+            content,
+            seq,
+            created_at as createdAt
+      FROM channel_messages
+      WHERE channel_id = ?
+        AND COALESCE(message_source, '') != ?
+        AND thread_root_id IS NULL
+      ORDER BY seq DESC
+      LIMIT ?`).all(conversation.channelId, TASK_LIFECYCLE_SOURCE, limit)
+        .reverse();
+}
+function loadLatestScopeMessage(db, conversation) {
+    if (conversation.threadRootId) {
+        if (conversation.replyTarget.startsWith('dm:@')) {
+            const row = db.prepare(`SELECT message_id as messageId,
+                seq
+          FROM channel_messages
+          WHERE channel_id = ?
+            AND COALESCE(message_source, '') != ?
+            AND (
+              thread_root_id = ?
+              OR (thread_root_id IS NULL AND target = ?)
+            )
+          ORDER BY seq DESC
+          LIMIT 1`).get(conversation.channelId, TASK_LIFECYCLE_SOURCE, conversation.threadRootId, conversation.replyTarget);
+            return row ?? null;
+        }
+        const row = db.prepare(`SELECT message_id as messageId,
+              seq
+       FROM channel_messages
+       WHERE channel_id = ?
+         AND COALESCE(message_source, '') != ?
+         AND thread_root_id = ?
+       ORDER BY seq DESC
+       LIMIT 1`).get(conversation.channelId, TASK_LIFECYCLE_SOURCE, conversation.threadRootId);
+        return row ?? null;
+    }
+    if (conversation.replyTarget.startsWith('dm:@')) {
+        const row = db.prepare(`SELECT message_id as messageId,
+              seq
+       FROM channel_messages
+       WHERE channel_id = ?
+         AND COALESCE(message_source, '') != ?
+         AND thread_root_id IS NULL
+         AND target = ?
+       ORDER BY seq DESC
+       LIMIT 1`).get(conversation.channelId, TASK_LIFECYCLE_SOURCE, conversation.replyTarget);
+        return row ?? null;
+    }
+    const row = db.prepare(`SELECT message_id as messageId,
+            seq
+     FROM channel_messages
+     WHERE channel_id = ?
+       AND COALESCE(message_source, '') != ?
+       AND thread_root_id IS NULL
+     ORDER BY seq DESC
+     LIMIT 1`).get(conversation.channelId, TASK_LIFECYCLE_SOURCE);
+    return row ?? null;
+}
+function loadThreadRootMessageContent(db, conversation) {
+    if (!conversation.threadRootId)
+        return null;
+    const row = db.prepare(`SELECT content
+       FROM channel_messages
+      WHERE channel_id = ?
+        AND (
+          thread_root_id = ?
+          OR message_id = ?
+        )
+      ORDER BY seq ASC
+      LIMIT 1`).get(conversation.channelId, conversation.threadRootId, conversation.threadRootId);
+    return row?.content ?? null;
+}
+function loadLinkedTasks(db, conversation) {
+    if (conversation.threadRootId) {
+        const summary = getThreadCollaborationSummary(db, {
+            channelId: conversation.channelId,
+            threadRootId: conversation.threadRootId,
+        });
+        if (summary.boundTask) {
+            const taskRefRow = db.prepare(`SELECT agent_task_ref as agentTaskRef,
+                claimed_by_name as claimedByName,
+                description,
+                message_id as messageId
+           FROM tasks
+          WHERE task_id = ?
+          LIMIT 1`).get(summary.boundTask.taskId);
+            return [{
+                    taskId: summary.boundTask.taskId,
+                    agentTaskRef: taskRefRow?.agentTaskRef ?? null,
+                    taskNumber: summary.boundTask.taskNumber,
+                    title: summary.boundTask.title,
+                    status: summary.boundTask.status,
+                    claimedByName: taskRefRow?.claimedByName ?? null,
+                    description: taskRefRow?.description ?? null,
+                    messageId: taskRefRow?.messageId ?? null,
+                    channelId: conversation.channelId,
+                    sourceTarget: conversation.replyTarget,
+                }];
+        }
+    }
+    return db.prepare(`SELECT t.task_id as taskId,
+            t.agent_task_ref as agentTaskRef,
+            t.task_number as taskNumber,
+            t.title,
+            t.status,
+            t.claimed_by_name as claimedByName,
+            t.description,
+            t.message_id as messageId,
+            COALESCE(t.dm_target, cm.target) as sourceTarget,
+            t.channel_id as channelId,
+            ch.name as channelName
+       FROM tasks t
+       LEFT JOIN channel_messages cm ON cm.message_id = t.message_id
+       LEFT JOIN channels ch ON ch.channel_id = t.channel_id
+      WHERE t.channel_id = ?
+        AND COALESCE(t.dm_target, cm.target) = ?
+      ORDER BY t.updated_at DESC, t.created_at DESC
+      LIMIT 3`).all(conversation.channelId, conversation.replyTarget);
+}
+function loadLastRunError(db, conversationId) {
+    const row = db.prepare(`SELECT r.error
+       FROM conversations c
+       JOIN runs r ON r.session_key = c.session_key
+      WHERE c.id = ?
+        AND r.error IS NOT NULL
+        AND trim(r.error) != ''
+      ORDER BY r.started_at DESC
+      LIMIT 1`).get(conversationId);
+    return summarizeText(row?.error ?? null, 180);
+}
+function buildTaskThreadTarget(sourceTarget, messageId) {
+    const normalizedTarget = normalizeOptionalText(sourceTarget);
+    if (!normalizedTarget || !messageId)
+        return null;
+    if (!(normalizedTarget.startsWith('#') || normalizedTarget.startsWith('dm:@')))
+        return null;
+    if ((normalizedTarget.startsWith('#') && normalizedTarget.includes(':')) || (normalizedTarget.startsWith('dm:@') && normalizedTarget.split(':').length >= 3)) {
+        return normalizedTarget;
+    }
+    return `${normalizedTarget}:${buildThreadShortId(messageId)}`;
+}
+function toLinkedTaskSummary(task) {
+    return {
+        taskId: task.taskId,
+        agentTaskRef: task.agentTaskRef,
+        taskNumber: task.taskNumber,
+        title: task.title,
+        status: task.status,
+        threadTarget: buildTaskThreadTarget(task.sourceTarget ?? (task.channelId?.startsWith('dm:') ? null : `#${task.channelName ?? task.channelId ?? ''}`), task.messageId ?? null),
+    };
+}
+function toActiveHandoffSummary(record) {
+    if (!record)
+        return null;
+    return {
+        handoffId: record.handoffId,
+        mode: record.mode,
+        status: record.status,
+        sourceConversationId: record.sourceConversationId,
+        targetConversationId: record.targetConversationId,
+        targetReplyTarget: record.targetReplyTarget,
+        sourceTarget: record.payload.sourceTarget,
+        goal: record.payload.goal,
+        error: record.payload.error,
+        updatedAt: record.updatedAt,
+    };
+}
+function deriveMyRole(params) {
+    if (params.boundTask?.claimedByName === params.agent.name)
+        return 'task_owner';
+    if (params.boundTask && params.participants.includes(params.agent.name))
+        return 'task_participant';
+    if (params.ownerAgentId === params.agent.agentId || params.ownerName === params.agent.name)
+        return 'owner';
+    if (params.participants.includes(params.agent.name))
+        return 'participant';
+    if (params.conversation.surfaceKind === 'dm' && params.conversation.isPrimaryThread)
+        return 'primary_dm_agent';
+    if (params.conversation.surfaceKind === 'dm_thread')
+        return 'dm_thread_agent';
+    if (params.conversation.surfaceKind === 'channel')
+        return 'channel_member';
+    if (params.conversation.surfaceKind === 'channel_thread')
+        return 'thread_member';
+    return 'observer';
+}
+function buildNextStep(params) {
+    if (params.conversation.status === 'active' || params.conversation.status === 'recovering') {
+        return 'Continue work on this surface';
+    }
+    if (params.conversation.status === 'awaiting_approval') {
+        return 'Wait for approval or a new user reply';
+    }
+    if (params.conversation.queuedPromptCount > 0) {
+        return `Process ${params.conversation.queuedPromptCount} queued prompt(s)`;
+    }
+    if (params.linkedTask && params.linkedTask.status !== 'done') {
+        return `Advance ${formatTaskRef(params.linkedTask.agentTaskRef, params.linkedTask.taskNumber)}`;
+    }
+    if (params.lastUserMessage) {
+        return 'Respond to the latest user message';
+    }
+    return null;
+}
+function formatConversationSummaryText(replyTarget, status, summary) {
+    const lines = [
+        `[Conversation summary] ${replyTarget}`,
+        `status: ${status}`,
+        `unread: ${summary.unreadCount}`,
+        `queued_prompts: ${summary.queuedPromptCount}`,
+    ];
+    if (summary.goal)
+        lines.push(`goal: ${summary.goal}`);
+    if (summary.recentState)
+        lines.push(`recent_state: ${summary.recentState}`);
+    if (summary.blockers.length > 0)
+        lines.push(`blockers: ${summary.blockers.join('; ')}`);
+    if (summary.nextStep)
+        lines.push(`next_step: ${summary.nextStep}`);
+    if (summary.myRole)
+        lines.push(`my_role: ${summary.myRole}`);
+    if (summary.ownerName)
+        lines.push(`owner: @${summary.ownerName}`);
+    if (summary.linkedTaskRefs.length > 0)
+        lines.push(`linked_tasks: ${summary.linkedTaskRefs.join(', ')}`);
+    if (summary.boundTask) {
+        lines.push(`bound_task: ${formatTaskRef(summary.boundTask.agentTaskRef, summary.boundTask.taskNumber)} [${summary.boundTask.status}]`);
+    }
+    if (summary.participants.length > 0) {
+        lines.push(`participants: ${summary.participants.map((name) => `@${name}`).join(', ')}`);
+    }
+    if (summary.activeHandoff) {
+        lines.push(`active_handoff: ${summary.activeHandoff.handoffId} ${summary.activeHandoff.mode} [${summary.activeHandoff.status}] -> ${summary.activeHandoff.targetReplyTarget}`);
+    }
+    if (summary.lastMessage) {
+        lines.push(`last_message: @${summary.lastMessage.senderName} ${summary.lastMessage.preview}`);
+    }
+    return lines.join('\n');
+}
+function formatTaskRef(agentTaskRef, taskNumber) {
+    return agentTaskRef?.trim() ? `${agentTaskRef} · #t${taskNumber}` : `#t${taskNumber}`;
+}
+function summarizeText(value, limit) {
+    const normalized = String(value ?? '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalized)
+        return null;
+    return normalized.length > limit ? `${normalized.slice(0, limit - 3)}...` : normalized;
+}
+function normalizeOptionalText(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized ? normalized : null;
+}
+function parseConversationSummaryPayload(summaryJson) {
+    try {
+        const parsed = JSON.parse(summaryJson);
+        return {
+            goal: typeof parsed?.goal === 'string' ? parsed.goal : null,
+            recentState: typeof parsed?.recentState === 'string' ? parsed.recentState : null,
+            blockers: Array.isArray(parsed?.blockers) ? parsed.blockers.filter((item) => typeof item === 'string') : [],
+            nextStep: typeof parsed?.nextStep === 'string' ? parsed.nextStep : null,
+            lastUserMessage: typeof parsed?.lastUserMessage === 'string' ? parsed.lastUserMessage : null,
+            lastAgentMessage: typeof parsed?.lastAgentMessage === 'string' ? parsed.lastAgentMessage : null,
+            linkedTaskRefs: Array.isArray(parsed?.linkedTaskRefs) ? parsed.linkedTaskRefs.filter((item) => typeof item === 'string') : [],
+            linkedTaskTitles: Array.isArray(parsed?.linkedTaskTitles) ? parsed.linkedTaskTitles.filter((item) => typeof item === 'string') : [],
+            unreadCount: Number(parsed?.unreadCount ?? 0) || 0,
+            queuedPromptCount: Number(parsed?.queuedPromptCount ?? 0) || 0,
+            lastMessageAt: typeof parsed?.lastMessageAt === 'string' ? parsed.lastMessageAt : null,
+            lastMessage: parsed?.lastMessage && typeof parsed.lastMessage === 'object' && typeof parsed.lastMessage.messageId === 'string'
+                ? {
+                    messageId: parsed.lastMessage.messageId,
+                    target: typeof parsed.lastMessage.target === 'string' ? parsed.lastMessage.target : '',
+                    senderName: typeof parsed.lastMessage.senderName === 'string' ? parsed.lastMessage.senderName : 'unknown',
+                    senderType: typeof parsed.lastMessage.senderType === 'string' ? parsed.lastMessage.senderType : 'unknown',
+                    preview: typeof parsed.lastMessage.preview === 'string' ? parsed.lastMessage.preview : '',
+                    createdAt: typeof parsed.lastMessage.createdAt === 'string' ? parsed.lastMessage.createdAt : '',
+                }
+                : null,
+            linkedTasks: Array.isArray(parsed?.linkedTasks)
+                ? parsed.linkedTasks.filter((item) => Boolean(item
+                    && typeof item === 'object'
+                    && typeof item.taskId === 'string'
+                    && typeof item.taskNumber === 'number'
+                    && typeof item.title === 'string'
+                    && typeof item.status === 'string')).map((item) => ({
+                    taskId: item.taskId,
+                    agentTaskRef: typeof item.agentTaskRef === 'string' ? item.agentTaskRef : null,
+                    taskNumber: item.taskNumber,
+                    title: item.title,
+                    status: item.status,
+                    threadTarget: typeof item.threadTarget === 'string' ? item.threadTarget : null,
+                }))
+                : [],
+            boundTask: parsed?.boundTask && typeof parsed.boundTask === 'object' && typeof parsed.boundTask.taskId === 'string'
+                ? {
+                    taskId: parsed.boundTask.taskId,
+                    agentTaskRef: typeof parsed.boundTask.agentTaskRef === 'string' ? parsed.boundTask.agentTaskRef : null,
+                    taskNumber: Number(parsed.boundTask.taskNumber ?? 0) || 0,
+                    title: typeof parsed.boundTask.title === 'string' ? parsed.boundTask.title : '',
+                    status: typeof parsed.boundTask.status === 'string' ? parsed.boundTask.status : 'todo',
+                    threadTarget: typeof parsed.boundTask.threadTarget === 'string' ? parsed.boundTask.threadTarget : null,
+                    description: typeof parsed.boundTask.description === 'string' ? parsed.boundTask.description : null,
+                    claimedByName: typeof parsed.boundTask.claimedByName === 'string' ? parsed.boundTask.claimedByName : null,
+                }
+                : null,
+            ownerAgentId: typeof parsed?.ownerAgentId === 'string' ? parsed.ownerAgentId : null,
+            ownerName: typeof parsed?.ownerName === 'string' ? parsed.ownerName : null,
+            participants: Array.isArray(parsed?.participants) ? parsed.participants.filter((item) => typeof item === 'string') : [],
+            myRole: typeof parsed?.myRole === 'string' ? parsed.myRole : null,
+            activeHandoff: parsed?.activeHandoff && typeof parsed.activeHandoff === 'object' && typeof parsed.activeHandoff.handoffId === 'string'
+                ? {
+                    handoffId: parsed.activeHandoff.handoffId,
+                    mode: parsed.activeHandoff.mode,
+                    status: parsed.activeHandoff.status,
+                    sourceConversationId: typeof parsed.activeHandoff.sourceConversationId === 'string' ? parsed.activeHandoff.sourceConversationId : '',
+                    targetConversationId: typeof parsed.activeHandoff.targetConversationId === 'string' ? parsed.activeHandoff.targetConversationId : null,
+                    targetReplyTarget: typeof parsed.activeHandoff.targetReplyTarget === 'string' ? parsed.activeHandoff.targetReplyTarget : '',
+                    sourceTarget: typeof parsed.activeHandoff.sourceTarget === 'string' ? parsed.activeHandoff.sourceTarget : null,
+                    goal: typeof parsed.activeHandoff.goal === 'string' ? parsed.activeHandoff.goal : '',
+                    error: typeof parsed.activeHandoff.error === 'string' ? parsed.activeHandoff.error : null,
+                    updatedAt: typeof parsed.activeHandoff.updatedAt === 'string' ? parsed.activeHandoff.updatedAt : '',
+                }
+                : null,
+        };
+    }
+    catch {
+        return {
+            goal: null,
+            recentState: null,
+            blockers: [],
+            nextStep: null,
+            lastUserMessage: null,
+            lastAgentMessage: null,
+            linkedTaskRefs: [],
+            linkedTaskTitles: [],
+            unreadCount: 0,
+            queuedPromptCount: 0,
+            lastMessageAt: null,
+            lastMessage: null,
+            linkedTasks: [],
+            boundTask: null,
+            ownerAgentId: null,
+            ownerName: null,
+            participants: [],
+            myRole: null,
+            activeHandoff: null,
+        };
+    }
+}