@bbigbang/core 0.1.0

package/dist/web/routes/handoff.js

@@ -0,0 +1,288 @@
+import { AgentVisibility } from '../agentVisibility.js';
+import { formatConversationHandoff, getHandoffState, } from '../conversationHandoffs.js';
+import { formatConversationSummary, refreshConversationSummariesForConversationIds, refreshConversationSummary, } from '../conversationSummaries.js';
+import { resolveChannelFromTarget, resolveDefaultReplyTarget, resolveThreadRootId, } from '../conversationTargets.js';
+import { findActiveConversationRunId } from '../routeHelpers.js';
+import { startConversationHandoff } from '../sameAgentHandoffs.js';
+import { getStaleTaskThreadReopenedRunBlock } from '../taskThreadRuntimeClosure.js';
+import { getBoundTaskForThread } from '../threadTaskBindings.js';
+import { buildRollingSummarySectionBody } from '../rollingConversationSummary.js';
+function normalizeRequiredText(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function normalizeOptionalText(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => (typeof item === 'string' ? item.trim() : ''))
+        .filter(Boolean);
+}
+function getCanonicalBoundTaskRef(boundTask) {
+    if (!boundTask)
+        return null;
+    const prefixedRef = typeof boundTask.agentTaskRef === 'string' ? boundTask.agentTaskRef.trim() : '';
+    return prefixedRef || null;
+}
+function annotateSourceSummaryForHandoff(params) {
+    if (!params.sourceSummary)
+        return null;
+    if (params.mode !== 'continue_there')
+        return params.sourceSummary;
+    const lines = params.sourceSummary.split('\n');
+    const statusLineIndex = lines.findIndex((line) => line.startsWith('Status: '));
+    if (statusLineIndex >= 0) {
+        lines[statusLineIndex] = `${lines[statusLineIndex]} (pre-handoff snapshot)`;
+    }
+    else {
+        lines.unshift('Handoff: continue_there (pre-handoff snapshot)');
+    }
+    return lines.join('\n');
+}
+export function registerAgentHandoffRoutes(params) {
+    const { app, db, conversationManager, humanUserName, broadcastConversationStatus } = params;
+    const visibility = new AgentVisibility(db);
+    app.post('/api/internal/agent/:agentId/handoff', async (req, reply) => {
+        const { agentId } = req.params;
+        const agent = conversationManager.getAgent(agentId);
+        if (!agent) {
+            reply.code(404);
+            return { error: 'Agent not found' };
+        }
+        const sourceConversationId = typeof req.body?.conversationId === 'string' ? req.body.conversationId.trim() : '';
+        const requestedTarget = typeof req.body?.target === 'string' ? req.body.target.trim() : '';
+        const mode = (typeof req.body?.mode === 'string' ? req.body.mode.trim() : 'delegate_only');
+        const goal = normalizeRequiredText(req.body?.goal);
+        if (!sourceConversationId) {
+            reply.code(400);
+            return { error: 'conversationId is required' };
+        }
+        if (!requestedTarget) {
+            reply.code(400);
+            return { error: 'target is required' };
+        }
+        if (!goal) {
+            reply.code(400);
+            return { error: 'goal is required' };
+        }
+        if (!['delegate_only', 'continue_there', 'collab'].includes(mode)) {
+            reply.code(400);
+            return { error: `Invalid mode: ${req.body?.mode}` };
+        }
+        const sourceConversation = conversationManager.getConversation(sourceConversationId);
+        if (!sourceConversation || sourceConversation.agentId !== agentId) {
+            reply.code(400);
+            return { error: 'conversationId does not belong to this agent' };
+        }
+        if (requestedTarget.startsWith('#')) {
+            const channelId = resolveChannelFromTarget(requestedTarget, db);
+            if (!channelId) {
+                reply.code(404);
+                return { error: 'Target channel not found' };
+            }
+            if (visibility.resolveVisibleChannelId(agent, requestedTarget) === null) {
+                reply.code(403);
+                return { error: 'Agent is not a member of this channel' };
+            }
+        }
+        else if (!visibility.canSeeTarget(agent, requestedTarget)) {
+            reply.code(403);
+            return { error: 'Agent cannot access this target' };
+        }
+        const sourceReplyTarget = (resolveDefaultReplyTarget(db, sourceConversationId, humanUserName) ?? sourceConversation.replyTarget ?? '').trim();
+        const sourceConversationRunId = findActiveConversationRunId(db, sourceConversationId);
+        const sourceThreadRootId = resolveThreadRootId(sourceReplyTarget) ?? sourceConversation.threadRootId ?? null;
+        const sourceChannelId = sourceConversation.threadKind === 'direct'
+            ? (sourceConversation.agentId ? `dm:${sourceConversation.agentId}` : null)
+            : (sourceConversation.channelId ?? null);
+        const sourceBoundTask = sourceChannelId && sourceThreadRootId
+            ? getBoundTaskForThread(db, { channelId: sourceChannelId, threadRootId: sourceThreadRootId })
+            : undefined;
+        const staleReopenedRun = getStaleTaskThreadReopenedRunBlock(db, {
+            conversationId: sourceConversationId,
+            runId: sourceConversationRunId,
+            taskId: sourceBoundTask?.taskId,
+        });
+        if (staleReopenedRun) {
+            reply.code(409);
+            return {
+                error: 'This task-thread was reopened by a user follow-up. Stop this old review-closing run instead of handing off stale context.',
+            };
+        }
+        const targetConversationId = visibility.ensureVisibleConversationId(agent, conversationManager, requestedTarget);
+        if (!targetConversationId) {
+            reply.code(404);
+            return { error: 'Conversation not found for the requested target' };
+        }
+        const targetConversation = conversationManager.getConversation(targetConversationId);
+        if (!targetConversation || targetConversation.agentId !== agentId) {
+            reply.code(404);
+            return { error: 'Target conversation not found' };
+        }
+        const targetReplyTarget = (resolveDefaultReplyTarget(db, targetConversationId, humanUserName) ?? targetConversation.replyTarget ?? '').trim();
+        if (!sourceReplyTarget || !targetReplyTarget) {
+            reply.code(400);
+            return { error: 'Unable to resolve handoff targets' };
+        }
+        if (sourceConversationId === targetConversationId || sourceReplyTarget === targetReplyTarget) {
+            reply.code(400);
+            return { error: 'Source and target must be different work surfaces' };
+        }
+        if (mode === 'continue_there' && !sourceConversationRunId) {
+            reply.code(409);
+            return { error: 'continue_there requires an active source run' };
+        }
+        const sourceSummary = refreshConversationSummary(db, agent, sourceConversationId);
+        const sourceSummaryBoundTask = sourceSummary?.summary.boundTask ?? null;
+        const handoffTaskId = sourceSummaryBoundTask?.taskId ?? sourceBoundTask?.taskId ?? null;
+        const handoffTaskNumber = sourceSummaryBoundTask?.taskNumber ?? sourceBoundTask?.taskNumber ?? null;
+        const explicitRelatedTaskRef = normalizeOptionalText(req.body?.context?.related_task_ref);
+        const sourceBoundTaskRef = getCanonicalBoundTaskRef(sourceSummaryBoundTask);
+        const sourceSummaryText = annotateSourceSummaryForHandoff({
+            mode,
+            sourceSummary: sourceSummary ? formatConversationSummary(sourceSummary) : null,
+        });
+        const sourceRollingSummary = buildRollingSummarySectionBody(db, sourceConversationId);
+        const payload = {
+            goal,
+            whyNow: normalizeOptionalText(req.body?.context?.why_now),
+            constraints: normalizeStringArray(req.body?.context?.constraints),
+            alreadyDone: normalizeStringArray(req.body?.context?.already_done),
+            expectedOutput: normalizeOptionalText(req.body?.context?.expected_output),
+            sourceTarget: sourceReplyTarget,
+            relatedTaskRef: explicitRelatedTaskRef ?? sourceBoundTaskRef,
+            optionalRefs: normalizeStringArray(req.body?.context?.optional_refs),
+            sourceSummary: sourceSummaryText,
+            sourceRollingSummary,
+            targetRunId: null,
+            cancelRunId: null,
+            completionMessageId: null,
+            error: null,
+            sourceContext: sourceSummary
+                ? {
+                    lastUserMessage: sourceSummary.summary.lastUserMessage,
+                    lastAgentMessage: sourceSummary.summary.lastAgentMessage,
+                    boundTaskRef: sourceBoundTaskRef,
+                    boundTaskTitle: sourceSummary.summary.boundTask?.title ?? null,
+                    ownerName: sourceSummary.summary.ownerName,
+                    participants: sourceSummary.summary.participants,
+                    myRole: sourceSummary.summary.myRole,
+                }
+                : null,
+        };
+        const handoff = await startConversationHandoff({
+            agentId,
+            db,
+            conversationManager,
+            humanUserName,
+            sourceConversationId,
+            sourceConversationRunId,
+            sourceReplyTarget,
+            targetConversationId,
+            targetReplyTarget,
+            mode,
+            payload,
+            taskId: handoffTaskId,
+            taskNumber: handoffTaskNumber,
+            broadcastConversationStatus,
+        });
+        refreshConversationSummariesForConversationIds(db, (targetAgentId) => conversationManager.getAgent(targetAgentId), [sourceConversationId, targetConversationId]);
+        return {
+            handoff: {
+                handoffId: handoff.handoffId,
+                agentId,
+                status: handoff.status,
+                mode,
+                sourceConversationId,
+                sourceReplyTarget,
+                targetConversationId,
+                targetReplyTarget,
+                workflowKind: 'generic',
+                sourceDisposition: mode === 'continue_there' ? 'cancel_current_run' : 'keep_running',
+                taskId: handoffTaskId,
+                taskNumber: handoffTaskNumber,
+                payload,
+                queued: handoff.queued,
+                cancelRequested: handoff.cancelRequested,
+                ...(handoff.targetRunId ? { targetRunId: handoff.targetRunId } : {}),
+                ...(handoff.cancelRunId ? { cancelRunId: handoff.cancelRunId } : {}),
+                ...(handoff.error ? { error: handoff.error } : {}),
+                reportText: formatConversationHandoff({
+                    handoffId: handoff.handoffId,
+                    agentId,
+                    sourceConversationId,
+                    targetConversationId,
+                    targetReplyTarget,
+                    workflowKind: 'generic',
+                    sourceDisposition: mode === 'continue_there' ? 'cancel_current_run' : 'keep_running',
+                    taskId: handoffTaskId,
+                    taskNumber: handoffTaskNumber,
+                    mode,
+                    status: handoff.status,
+                    payload: {
+                        ...payload,
+                        ...(handoff.error ? { error: handoff.error } : {}),
+                    },
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                }),
+            },
+        };
+    });
+    app.get('/api/internal/agent/:agentId/handoffs/:handoffId', async (req, reply) => {
+        const { agentId, handoffId } = req.params;
+        if (!conversationManager.getAgent(agentId)) {
+            reply.code(404);
+            return { error: 'Agent not found' };
+        }
+        const state = getHandoffState(db, handoffId);
+        if (!state || state.agentId !== agentId) {
+            reply.code(404);
+            return { error: 'Handoff not found' };
+        }
+        return {
+            handoff: {
+                handoffId: state.handoffId,
+                agentId: state.agentId,
+                sourceConversationId: state.sourceConversationId,
+                sourceReplyTarget: state.payload.sourceTarget,
+                targetConversationId: state.targetConversationId,
+                targetReplyTarget: state.targetReplyTarget,
+                workflowKind: state.workflowKind,
+                sourceDisposition: state.sourceDisposition,
+                taskId: state.taskId,
+                taskNumber: state.taskNumber,
+                mode: state.mode,
+                status: state.status,
+                payload: state.payload,
+                createdAt: state.createdAt,
+                updatedAt: state.updatedAt,
+                runs: state.runs.map((r) => ({
+                    runId: r.runId,
+                    agentId: r.agentId,
+                    disposition: r.disposition,
+                    createdAt: r.createdAt,
+                    completedAt: r.completedAt,
+                })),
+                reportText: formatConversationHandoff({
+                    handoffId: state.handoffId,
+                    agentId: state.agentId,
+                    sourceConversationId: state.sourceConversationId,
+                    targetConversationId: state.targetConversationId,
+                    targetReplyTarget: state.targetReplyTarget,
+                    workflowKind: state.workflowKind,
+                    sourceDisposition: state.sourceDisposition,
+                    taskId: state.taskId,
+                    taskNumber: state.taskNumber,
+                    mode: state.mode,
+                    status: state.status,
+                    payload: state.payload,
+                    createdAt: state.createdAt,
+                    updatedAt: state.updatedAt,
+                }),
+            },
+        };
+    });
+}

package/dist/web/routes/history.js

@@ -0,0 +1,345 @@
+import { AgentVisibility } from '../agentVisibility.js';
+import { CLEARED_TASK_ROOT_TARGET_GLOB } from '../clearedTaskRoots.js';
+import { findThreadRootMessageId } from '../threadRoots.js';
+import { resolveChannelFromTarget, resolveThreadRootId } from '../conversationTargets.js';
+import { buildFtsMatchQuery } from '../ftsQuery.js';
+import { recordRunSurfaceCatchUpRowsSeen, recordRunSurfaceRowsSeen, resolveRunWatermarkIdentity, } from '../runSurfaceWatermarks.js';
+import { advanceAgentSurfaceSeenThroughSeq } from '../collaborationSurfaceState.js';
+function parseBoundedPositiveInt(value, fallback, max) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return Math.min(Math.floor(parsed), max);
+}
+function parseOptionalPositiveInt(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return Math.floor(parsed);
+}
+function buildMessageScope(alias, channelId, threadRootId, target) {
+    const params = [channelId];
+    if (threadRootId !== null) {
+        params.push(threadRootId);
+        if (target?.startsWith('dm:@')) {
+            params.push(target);
+            return {
+                clause: `${alias}.channel_id = ? AND (${alias}.thread_root_id = ? OR (${alias}.thread_root_id IS NULL AND ${alias}.target = ?))`,
+                params,
+            };
+        }
+        return {
+            clause: `${alias}.channel_id = ? AND ${alias}.thread_root_id = ?`,
+            params,
+        };
+    }
+    if (target?.startsWith('dm:@')) {
+        params.push(target);
+        return {
+            clause: `${alias}.channel_id = ? AND ${alias}.thread_root_id IS NULL AND ${alias}.target = ?`,
+            params,
+        };
+    }
+    params.push(CLEARED_TASK_ROOT_TARGET_GLOB);
+    return {
+        clause: `${alias}.channel_id = ? AND ${alias}.thread_root_id IS NULL AND ${alias}.target NOT GLOB ?`,
+        params,
+    };
+}
+function resolveReadableChannelId(db, visibility, agent, target) {
+    const visibleChannelId = visibility.resolveVisibleChannelId(agent, target);
+    if (visibleChannelId)
+        return { channelId: visibleChannelId };
+    if (target.startsWith('#')) {
+        const channelId = resolveChannelFromTarget(target, db);
+        if (!channelId)
+            return { channelId: null, errorCode: 400, error: `Cannot resolve channel: ${target}` };
+        return { channelId: null, errorCode: 403, error: 'Agent is not a member of this channel' };
+    }
+    return { channelId: null, errorCode: 403, error: 'Agent cannot access this target' };
+}
+export function registerAgentHistoryRoutes(app, db, conversationManager) {
+    const visibility = new AgentVisibility(db);
+    app.get('/api/internal/agent/:agentId/search', async (req, reply) => {
+        const { agentId } = req.params;
+        const agent = conversationManager.getAgent(agentId);
+        if (!agent) {
+            reply.code(404);
+            return { error: 'Agent not found' };
+        }
+        const query = typeof req.query.q === 'string' ? req.query.q.trim() : '';
+        if (!query) {
+            reply.code(400);
+            return { error: 'q query parameter is required' };
+        }
+        const ftsQuery = buildFtsMatchQuery(query, { prefix: true });
+        if (!ftsQuery) {
+            reply.code(400);
+            return { error: 'q query parameter is required' };
+        }
+        const limit = parseBoundedPositiveInt(req.query.limit, 10, 20);
+        const visibleChannelIds = Array.from(new Set([`dm:${agentId}`, ...(agent.channelIds ?? [])]));
+        const whereParts = [
+            `cm.channel_id IN (${visibleChannelIds.map(() => '?').join(', ')})`,
+            'cm.target NOT GLOB ?',
+        ];
+        const params = [ftsQuery, ...visibleChannelIds, CLEARED_TASK_ROOT_TARGET_GLOB];
+        const channelTarget = typeof req.query.channel === 'string' ? req.query.channel.trim() : '';
+        if (channelTarget) {
+            const resolved = resolveReadableChannelId(db, visibility, agent, channelTarget);
+            if (!resolved.channelId) {
+                reply.code(resolved.errorCode ?? 400);
+                return { error: resolved.error ?? `Cannot resolve channel: ${channelTarget}` };
+            }
+            const threadRootId = resolveThreadRootId(channelTarget);
+            if (threadRootId !== null || channelTarget.startsWith('dm:@')) {
+                const scope = buildMessageScope('cm', resolved.channelId, threadRootId, channelTarget);
+                whereParts.push(scope.clause);
+                params.push(...scope.params);
+            }
+            else {
+                whereParts.push('cm.channel_id = ?');
+                params.push(resolved.channelId);
+            }
+        }
+        const rows = db.prepare(`SELECT
+         cm.message_id as messageId,
+         cm.channel_id as channelId,
+         cm.sender_id as senderId,
+         cm.sender_name as senderName,
+         cm.sender_type as senderType,
+         cm.target,
+         cm.content,
+         cm.seq,
+         cm.created_at as createdAt,
+         snippet(channel_messages_fts, 4, '[', ']', '...', 12) as snippet
+       FROM channel_messages_fts
+       JOIN channel_messages cm ON cm.message_id = channel_messages_fts.message_id
+       WHERE channel_messages_fts MATCH ?
+         AND ${whereParts.join(' AND ')}
+       ORDER BY bm25(channel_messages_fts), cm.created_at DESC
+       LIMIT ?`).all(...params, limit);
+        return {
+            results: rows.map((row) => ({
+                id: row.messageId,
+                target: row.target,
+                senderName: row.senderName,
+                senderType: row.senderType,
+                content: row.content,
+                seq: row.seq,
+                createdAt: new Date(row.createdAt).toISOString(),
+                snippet: row.snippet ?? row.content,
+            })),
+        };
+    });
+    app.get('/api/internal/agent/:agentId/history', async (req, reply) => {
+        const { agentId } = req.params;
+        const agent = conversationManager.getAgent(agentId);
+        if (!agent) {
+            reply.code(404);
+            return { error: 'Agent not found' };
+        }
+        const { channel, limit: limitStr, around: aroundStr, before: beforeStr, after: afterStr, include_root: includeRootStr, runId: runIdStr, conversationId: conversationIdStr, } = req.query;
+        if (!channel) {
+            reply.code(400);
+            return { error: 'channel query parameter is required' };
+        }
+        const runId = runIdStr?.trim() || null;
+        const conversationId = conversationIdStr?.trim() || null;
+        if (conversationId) {
+            const conversation = conversationManager.getConversation(conversationId);
+            if (!conversation || conversation.agentId !== agentId) {
+                reply.code(400);
+                return { error: 'conversationId does not belong to this agent' };
+            }
+        }
+        const watermarkIdentity = resolveRunWatermarkIdentity(db, agentId, { runId, conversationId });
+        if (runId && !watermarkIdentity) {
+            reply.code(400);
+            return { error: 'runId does not belong to this agent conversation' };
+        }
+        const resolved = resolveReadableChannelId(db, visibility, agent, channel);
+        if (!resolved.channelId) {
+            reply.code(resolved.errorCode ?? 400);
+            return { error: resolved.error ?? `Cannot resolve channel: ${channel}` };
+        }
+        const limit = parseBoundedPositiveInt(limitStr, 50, 100);
+        const before = parseOptionalPositiveInt(beforeStr);
+        const after = parseOptionalPositiveInt(afterStr);
+        const around = typeof aroundStr === 'string' ? aroundStr.trim() : '';
+        const includeRoot = typeof includeRootStr === 'string' && ['1', 'true', 'yes'].includes(includeRootStr.trim().toLowerCase());
+        if (around && (before !== undefined || after !== undefined)) {
+            reply.code(400);
+            return { error: 'around cannot be combined with before or after' };
+        }
+        const targetThreadRootId = resolveThreadRootId(channel);
+        const scope = buildMessageScope('cm', resolved.channelId, targetThreadRootId, channel);
+        const taskJoinSelect = `cm.message_id as messageId, cm.channel_id as channelId, cm.sender_id as senderId,
+                  cm.sender_name as senderName, cm.sender_type as senderType,
+                  cm.target, cm.content, cm.seq, cm.created_at as createdAt, cm.thread_root_id as threadRootId,
+                  t.task_number as taskNumber, t.status as taskStatus, t.claimed_by_name as taskAssigneeName`;
+        const taskJoin = `LEFT JOIN tasks t ON t.message_id = cm.message_id`;
+        const selectRows = (extraWhere, extraParams, order, rowLimit) => db
+            .prepare(`SELECT ${taskJoinSelect}
+           FROM channel_messages cm ${taskJoin}
+           WHERE ${scope.clause}${extraWhere ? ` AND ${extraWhere}` : ''}
+           ORDER BY cm.seq ${order} LIMIT ?`)
+            .all(...scope.params, ...extraParams, rowLimit);
+        const findAroundAnchorSeq = () => {
+            if (!around)
+                return null;
+            if (/^\d+$/.test(around)) {
+                const row = db.prepare(`SELECT cm.seq as seq
+           FROM channel_messages cm
+           WHERE ${scope.clause} AND cm.seq = ?
+           LIMIT 1`).get(...scope.params, Number(around));
+                return row?.seq ?? null;
+            }
+            const row = db.prepare(`SELECT cm.seq as seq
+         FROM channel_messages cm
+         WHERE ${scope.clause} AND cm.message_id LIKE ?
+         ORDER BY cm.seq ASC
+         LIMIT 1`).get(...scope.params, `${around}%`);
+            return row?.seq ?? null;
+        };
+        let rows;
+        if (around) {
+            const anchorSeq = findAroundAnchorSeq();
+            if (anchorSeq === null) {
+                reply.code(404);
+                return { error: `Cannot resolve message around ${around}` };
+            }
+            const beforeBase = Math.floor((limit - 1) / 2);
+            const afterBase = Math.max(limit - beforeBase - 1, 0);
+            let beforeRows = selectRows('cm.seq < ?', [anchorSeq], 'DESC', beforeBase);
+            let afterRows = selectRows('cm.seq > ?', [anchorSeq], 'ASC', afterBase);
+            if (beforeRows.length < beforeBase) {
+                afterRows = selectRows('cm.seq > ?', [anchorSeq], 'ASC', afterBase + (beforeBase - beforeRows.length));
+            }
+            if (afterRows.length < afterBase) {
+                beforeRows = selectRows('cm.seq < ?', [anchorSeq], 'DESC', beforeBase + (afterBase - afterRows.length));
+            }
+            const anchorRows = selectRows('cm.seq = ?', [anchorSeq], 'ASC', 1);
+            rows = beforeRows.reverse().concat(anchorRows, afterRows);
+        }
+        else if (after !== undefined) {
+            rows = selectRows('cm.seq > ?', [after], 'ASC', limit);
+        }
+        else if (before !== undefined) {
+            rows = selectRows('cm.seq < ?', [before], 'DESC', limit).reverse();
+        }
+        else {
+            rows = selectRows('', [], 'DESC', limit).reverse();
+        }
+        if (after !== undefined) {
+            recordRunSurfaceCatchUpRowsSeen(db, {
+                identity: watermarkIdentity,
+                agentId,
+                channelId: resolved.channelId,
+                threadRootId: targetThreadRootId,
+                afterSeq: after,
+                rows,
+                source: 'read_history',
+            });
+        }
+        else if (around || before === undefined) {
+            recordRunSurfaceRowsSeen(db, {
+                identity: watermarkIdentity,
+                agentId,
+                rows,
+                source: 'read_history',
+                threadRootIdOverride: targetThreadRootId,
+            });
+        }
+        if (rows.length > 0) {
+            const maxSeqBySurface = new Map();
+            for (const row of rows) {
+                const effectiveThreadRootId = row.threadRootId ?? targetThreadRootId;
+                const key = `${row.channelId}::${effectiveThreadRootId ?? ''}`;
+                const current = maxSeqBySurface.get(key);
+                if (!current || row.seq > current.maxSeq) {
+                    maxSeqBySurface.set(key, {
+                        channelId: row.channelId,
+                        threadRootId: effectiveThreadRootId,
+                        maxSeq: row.seq,
+                    });
+                }
+            }
+            for (const surface of maxSeqBySurface.values()) {
+                advanceAgentSurfaceSeenThroughSeq(db, {
+                    agentId,
+                    channelId: surface.channelId,
+                    threadRootId: surface.threadRootId,
+                    seenThroughSeq: surface.maxSeq,
+                });
+            }
+        }
+        const hasOlder = rows.length > 0
+            ? !!db.prepare(`SELECT 1
+         FROM channel_messages cm
+         WHERE ${scope.clause} AND cm.seq < ?
+         LIMIT 1`).get(...scope.params, rows[0].seq)
+            : false;
+        const hasNewer = rows.length > 0
+            ? !!db.prepare(`SELECT 1
+         FROM channel_messages cm
+         WHERE ${scope.clause} AND cm.seq > ?
+         LIMIT 1`).get(...scope.params, rows[rows.length - 1].seq)
+            : false;
+        const messages = rows.map((r) => {
+            const ext = r;
+            return {
+                id: r.messageId,
+                target: r.target,
+                senderName: r.senderName,
+                senderType: r.senderType,
+                content: r.content,
+                seq: r.seq,
+                createdAt: new Date(r.createdAt).toISOString(),
+                ...(ext.taskNumber != null ? {
+                    taskNumber: ext.taskNumber,
+                    taskStatus: ext.taskStatus,
+                    taskAssigneeName: ext.taskAssigneeName,
+                } : {}),
+            };
+        });
+        if (includeRoot && targetThreadRootId) {
+            const rootMessageId = findThreadRootMessageId(db, resolved.channelId, targetThreadRootId);
+            if (rootMessageId && !messages.some((message) => message.id === rootMessageId)) {
+                const rootRow = db.prepare(`SELECT ${taskJoinSelect}
+           FROM channel_messages cm ${taskJoin}
+           WHERE cm.channel_id = ?
+             AND cm.message_id = ?
+             AND cm.target NOT GLOB ?
+           LIMIT 1`).get(resolved.channelId, rootMessageId, CLEARED_TASK_ROOT_TARGET_GLOB);
+                if (rootRow) {
+                    messages.unshift({
+                        id: rootRow.messageId,
+                        target: rootRow.target,
+                        senderName: rootRow.senderName,
+                        senderType: rootRow.senderType,
+                        content: rootRow.content,
+                        seq: rootRow.seq,
+                        createdAt: new Date(rootRow.createdAt).toISOString(),
+                        ...(rootRow.taskNumber != null ? {
+                            taskNumber: rootRow.taskNumber,
+                            taskStatus: rootRow.taskStatus,
+                            taskAssigneeName: rootRow.taskAssigneeName,
+                        } : {}),
+                    });
+                }
+            }
+        }
+        return {
+            channel,
+            messages,
+            hasOlder,
+            hasNewer,
+            has_older: hasOlder,
+            has_newer: hasNewer,
+            has_more: hasOlder || hasNewer,
+        };
+    });
+}