@bbigbang/core 0.1.0

package/dist/web/channelMemoryNotes.js

@@ -0,0 +1,127 @@
+import { formatBeijingPromptTimestamp } from '@bbigbang/protocol';
+const LEGACY_CHANNELS_NOTE_PATH = 'notes/channels.md';
+const CHANNEL_NOTE_INSTRUCTION = 'Durable notes and reset markers for this channel.';
+const LEGACY_CHANNELS_INSTRUCTION = 'Durable summaries and reset markers for joined channels.';
+export function slugifyChannelNoteName(name) {
+    const normalized = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return normalized || 'channel';
+}
+export function channelMemoryNotePath(channelName) {
+    return `notes/channels/${slugifyChannelNoteName(channelName)}.md`;
+}
+export function buildChannelResetMarker(channelName, clearedAt) {
+    return [
+        '## History Reset',
+        `- Live chat history for #${channelName} was cleared at ${formatBeijingPromptTimestamp(clearedAt)}.`,
+        '- Treat older notes in this file as durable memory, not as the currently visible channel transcript.',
+        '- If asked what is currently visible in the channel, rely on current chat history or bigbang message read rather than older notes from before this reset.',
+    ].join('\n');
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildChannelNoteHeader(channelName) {
+    return [
+        `# Channel: #${channelName}`,
+        '',
+        CHANNEL_NOTE_INSTRUCTION,
+    ].join('\n');
+}
+function buildLegacyChannelsHeader() {
+    return [
+        '# Channel Summaries',
+        '',
+        LEGACY_CHANNELS_INSTRUCTION,
+    ].join('\n');
+}
+function buildLegacyResetEntry(channelName, clearedAt) {
+    return [
+        `## #${channelName}`,
+        `- Live chat history was cleared at ${formatBeijingPromptTimestamp(clearedAt)}.`,
+        '- Earlier bullets in this file are durable summaries, not necessarily the currently visible transcript.',
+    ].join('\n');
+}
+function isNotFoundError(error) {
+    const message = String(error?.message ?? error);
+    return message.startsWith('not_found:');
+}
+function stripLeadingHeader(content, header) {
+    const normalized = content.replace(/\r\n/g, '\n').trim();
+    const lines = header.split('\n');
+    const titleLine = lines[0] ?? '';
+    const introLine = lines.find((line, index) => index > 0 && line.trim().length > 0);
+    if (!normalized.startsWith(titleLine))
+        return normalized;
+    let remaining = normalized.slice(titleLine.length);
+    while (true) {
+        remaining = remaining.replace(/^(?:[ \t]*\n)+/u, '');
+        if (!introLine || !remaining.startsWith(introLine))
+            break;
+        remaining = remaining.slice(introLine.length);
+    }
+    return remaining.trim();
+}
+function stripManagedChannelResetBlocks(content, channelName) {
+    const channelPattern = new RegExp(String.raw `\n*## History Reset\n- Live chat history for #${escapeRegex(channelName)} was cleared at [^\n]+\.\n- Treat older notes in this file as durable memory, not as the currently visible channel transcript\.\n- If asked what is currently visible in the channel, rely on current chat history or (?:bigbang message read|read_history\(\.\.\.\)) rather than older notes from before this reset\.\n*`, 'g');
+    return content.replace(channelPattern, '\n\n').trim();
+}
+function stripManagedLegacyResetBlocks(content, channelName) {
+    const legacyPattern = new RegExp(String.raw `\n*## #${escapeRegex(channelName)}\n- Live chat history was cleared at [^\n]+\.\n- Earlier bullets in this file are durable summaries, not necessarily the currently visible transcript\.\n*`, 'g');
+    return content.replace(legacyPattern, '\n\n').trim();
+}
+function buildManagedNoteContent(params) {
+    const { existingContent, header, marker, stripMarkers } = params;
+    const withoutHeader = stripLeadingHeader(existingContent, header);
+    const remaining = stripMarkers(withoutHeader);
+    return remaining.length > 0 ? `${header}\n\n${marker}\n\n${remaining}\n` : `${header}\n\n${marker}\n`;
+}
+async function upsertMarkerFile(params) {
+    const { broker, agent, relativePath, marker, header, stripMarkers } = params;
+    if (!agent.nodeId || !agent.workspacePath)
+        return;
+    try {
+        const existing = await broker.readFile(agent.nodeId, agent.workspacePath, relativePath);
+        await broker.writeFile(agent.nodeId, agent.workspacePath, relativePath, buildManagedNoteContent({
+            existingContent: existing.content,
+            header,
+            marker,
+            stripMarkers,
+        }), 'overwrite');
+    }
+    catch (error) {
+        if (!isNotFoundError(error))
+            throw error;
+        await broker.writeFile(agent.nodeId, agent.workspacePath, relativePath, `${header}\n\n${marker}\n`, 'overwrite');
+    }
+}
+export async function appendChannelResetMarkers(params) {
+    const { broker, agents, channelName, clearedAt } = params;
+    const notePath = channelMemoryNotePath(channelName);
+    const channelMarker = buildChannelResetMarker(channelName, clearedAt);
+    const legacyMarker = buildLegacyResetEntry(channelName, clearedAt);
+    for (const agent of agents) {
+        if (!agent.nodeId || !agent.workspacePath)
+            continue;
+        await upsertMarkerFile({
+            broker,
+            agent,
+            relativePath: notePath,
+            marker: channelMarker,
+            header: buildChannelNoteHeader(channelName),
+            stripMarkers: (content) => stripManagedChannelResetBlocks(content, channelName),
+        });
+        await upsertMarkerFile({
+            broker,
+            agent,
+            relativePath: LEGACY_CHANNELS_NOTE_PATH,
+            marker: legacyMarker,
+            header: buildLegacyChannelsHeader(),
+            stripMarkers: (content) => stripManagedLegacyResetBlocks(content, channelName),
+        });
+    }
+}

package/dist/web/channelMentions.js

@@ -0,0 +1,10 @@
+import { extractMentionedNames } from '@bbigbang/protocol';
+export function findMentionedAgents(content, agents) {
+    const mentionedNames = extractMentionedNames(content);
+    if (mentionedNames.length === 0)
+        return [];
+    const agentByName = new Map(agents.map((agent) => [agent.name.toLowerCase(), agent]));
+    return mentionedNames
+        .map((name) => agentByName.get(name))
+        .filter((agent) => Boolean(agent));
+}

package/dist/web/channelMessageSequences.js

@@ -0,0 +1,19 @@
+export function allocateNextChannelMessageSeq(db, channelId) {
+    const tx = db.transaction((targetChannelId) => {
+        db.prepare(`INSERT INTO channel_message_sequences(channel_id, next_seq)
+       VALUES(
+         ?,
+         COALESCE((SELECT MAX(seq) FROM channel_messages WHERE channel_id = ?), 0) + 1
+       )
+       ON CONFLICT(channel_id) DO NOTHING`).run(targetChannelId, targetChannelId);
+        const row = db.prepare(`UPDATE channel_message_sequences
+       SET next_seq = next_seq + 1
+       WHERE channel_id = ?
+       RETURNING next_seq - 1 as seq`).get(targetChannelId);
+        if (!row) {
+            throw new Error(`Failed to allocate message sequence for channel ${targetChannelId}`);
+        }
+        return row.seq;
+    });
+    return tx(channelId);
+}

package/dist/web/channelSubscriptions.js

@@ -0,0 +1,26 @@
+export function upsertChannelSubscription(db, params) {
+    const now = params.lastActiveAt ?? Date.now();
+    const subscribedAt = params.subscribedAt ?? now;
+    db.prepare(`INSERT INTO channel_subscriptions(channel_id, agent_id, subscribed_at, last_active_at)
+     VALUES(?, ?, ?, ?)
+     ON CONFLICT(channel_id, agent_id) DO UPDATE SET
+       subscribed_at = MIN(channel_subscriptions.subscribed_at, excluded.subscribed_at),
+       last_active_at = MAX(channel_subscriptions.last_active_at, excluded.last_active_at)`).run(params.channelId, params.agentId, subscribedAt, now);
+}
+export function listChannelSubscriptions(db, channelId) {
+    return db.prepare(`SELECT s.agent_id as agentId,
+            a.name as name,
+            s.subscribed_at as subscribedAt,
+            s.last_active_at as lastActiveAt
+     FROM channel_subscriptions s
+     JOIN agents a ON a.agent_id = s.agent_id
+     WHERE s.channel_id = ?
+     ORDER BY s.last_active_at DESC, a.name ASC`).all(channelId);
+}
+export function deleteChannelSubscription(db, channelId, agentId) {
+    db.prepare(`DELETE FROM channel_subscriptions
+     WHERE channel_id = ? AND agent_id = ?`).run(channelId, agentId);
+}
+export function deleteChannelSubscriptionsForChannel(db, channelId) {
+    db.prepare('DELETE FROM channel_subscriptions WHERE channel_id = ?').run(channelId);
+}

package/dist/web/clearedTaskRoots.js

@@ -0,0 +1,10 @@
+export const CLEARED_TASK_ROOT_TARGET_PREFIX = '__cleared_task_root__:';
+export const CLEARED_TASK_ROOT_TARGET_GLOB = `${CLEARED_TASK_ROOT_TARGET_PREFIX}*`;
+export const CHANNEL_TASK_ROOT_PRESERVED_SOURCE = 'channel_task_root_preserved_after_clear';
+export function buildClearedTaskRootArchiveTarget(threadRootId) {
+    return `${CLEARED_TASK_ROOT_TARGET_PREFIX}${threadRootId.trim()}`;
+}
+export function isClearedTaskRootTarget(target) {
+    const normalized = target?.trim() ?? '';
+    return normalized.startsWith(CLEARED_TASK_ROOT_TARGET_PREFIX);
+}

package/dist/web/collaborationPromptGuidance.js

@@ -0,0 +1,36 @@
+export const NO_CLAIM_TASKS_FROM_NOTIFICATION_CONSTRAINT = 'Do not run bigbang task claim from this notification to make yourself owner.';
+export const NO_DIRECT_VISIBLE_OUTPUT_CONSTRAINT = 'Do not output user-visible text directly.';
+export const NO_TARGET_OR_CROSS_SURFACE_CONSTRAINT = 'Do not set target or post elsewhere.';
+export const NO_TARGET_CROSS_SURFACE_OR_VISIBLE_OUTPUT_CONSTRAINT = 'Do not set target, post elsewhere, or output user-visible text directly.';
+export function buildCurrentConversationRoutingConstraint(params) {
+    const targetAuthority = params?.targetAuthority ?? 'explicit';
+    const targetConstraint = targetAuthority === 'platform'
+        ? 'Do not set target unless the platform explicitly asks for it.'
+        : 'Do not set target unless explicitly asked.';
+    const parts = [
+        targetConstraint,
+        'Do not post elsewhere.',
+    ];
+    if (params?.includeVisibleOutputConstraint !== false) {
+        parts.push(NO_DIRECT_VISIBLE_OUTPUT_CONSTRAINT);
+    }
+    return parts.join(' ');
+}
+export function isClosedTaskPeerInboxNoopReply(content) {
+    const normalized = content
+        .replace(/\s+/g, ' ')
+        .replace(/[。.!！?？]+$/u, '')
+        .trim()
+        .toLowerCase();
+    if (!normalized || normalized.length > 240)
+        return false;
+    return [
+        /^no (additional|further|more)? ?(thread )?(reply|response|message|action|input|update) (is )?(needed|required|necessary)( from me)?( here)?$/u,
+        /^no (additional|further|more)? ?(context|updates?|input|reply|response) (to add|from me)( here)?$/u,
+        /^nothing (new |additional |further |more )?to (add|report|reply|send)( here)?$/u,
+        /^i have no (new|additional|further|more) (context|updates?|input|reply|response)( to add)?( here)?$/u,
+        /^(acknowledged|noted|收到|已知悉|了解)$/u,
+        /^(无需|不需要|不用)(再)?(回复|回应|发消息|补充|处理)$/u,
+        /^(没有|暂无)(新增|额外|更多)?(信息|补充|上下文|更新|回复)$/u,
+    ].some((pattern) => pattern.test(normalized));
+}

package/dist/web/collaborationSurfaceState.js

@@ -0,0 +1,140 @@
+import { getAgentMessageCheckpoint } from './messageCheckpoints.js';
+import { advanceAgentSurfaceNotificationAck, getAgentSurfaceNotificationState, listAgentSurfaceRosterParticipants, } from './notificationRounds.js';
+import { listRecentTargetParticipants, listTargetParticipants, TARGET_PARTICIPANT_ACTIVE_WINDOW_MS, } from './targetParticipants.js';
+function sortParticipants(participants) {
+    return [...participants].sort((left, right) => {
+        const leftRoleOrder = left.role === 'owner' ? 0 : 1;
+        const rightRoleOrder = right.role === 'owner' ? 0 : 1;
+        if (leftRoleOrder !== rightRoleOrder)
+            return leftRoleOrder - rightRoleOrder;
+        if (left.lastActiveAt !== right.lastActiveAt) {
+            return right.lastActiveAt - left.lastActiveAt;
+        }
+        return left.name.localeCompare(right.name);
+    });
+}
+function mergeParticipants(...lists) {
+    const merged = new Map();
+    for (const list of lists) {
+        for (const participant of list) {
+            const existing = merged.get(participant.agentId);
+            if (!existing) {
+                merged.set(participant.agentId, participant);
+                continue;
+            }
+            merged.set(participant.agentId, {
+                ...existing,
+                name: participant.name || existing.name,
+                role: existing.role === 'owner' || participant.role === 'owner' ? 'owner' : 'participant',
+                joinedAt: Math.min(existing.joinedAt, participant.joinedAt),
+                lastActiveAt: Math.max(existing.lastActiveAt, participant.lastActiveAt),
+            });
+        }
+    }
+    return sortParticipants([...merged.values()]);
+}
+function normalizeRootParticipants(participants) {
+    return participants.map((participant) => (participant.role === 'owner'
+        ? { ...participant, role: 'participant' }
+        : participant));
+}
+export function getUnifiedSurfaceUnreadCheckpoint(db, params) {
+    const notificationCheckpoint = getAgentSurfaceNotificationState(db, {
+        targetAgentId: params.agentId,
+        channelId: params.channelId,
+        threadRootId: params.threadRootId,
+    })?.ackedThroughSeq ?? 0;
+    const legacyCheckpoint = getAgentMessageCheckpoint(db, params.agentId, params.channelId, params.threadRootId ?? null);
+    return Math.max(notificationCheckpoint, legacyCheckpoint);
+}
+export function advanceAgentSurfaceSeenThroughSeq(db, params) {
+    const seenThroughSeq = Math.max(0, Math.floor(params.seenThroughSeq));
+    if (seenThroughSeq <= 0)
+        return;
+    advanceAgentSurfaceNotificationAck(db, {
+        targetAgentId: params.agentId,
+        channelId: params.channelId,
+        threadRootId: params.threadRootId ?? null,
+        ackedThroughSeq: seenThroughSeq,
+        now: params.now,
+    });
+}
+const CHANNEL_ROOT_ROSTER_LIMIT = 20;
+export function listUnifiedSurfaceParticipants(db, params) {
+    const isChannelRoot = !params.threadRootId?.trim();
+    const targetParticipants = listTargetParticipants(db, {
+        channelId: params.channelId,
+        threadRootId: params.threadRootId,
+    });
+    const rosterParticipants = listAgentSurfaceRosterParticipants(db, {
+        channelId: params.channelId,
+        threadRootId: params.threadRootId,
+        now: params.now,
+    });
+    const merged = mergeParticipants(isChannelRoot ? normalizeRootParticipants(targetParticipants) : targetParticipants, isChannelRoot ? normalizeRootParticipants(rosterParticipants) : rosterParticipants);
+    return isChannelRoot ? merged.slice(0, CHANNEL_ROOT_ROSTER_LIMIT) : merged;
+}
+export function listUnifiedRecentSurfaceParticipants(db, params) {
+    const now = params.now ?? Date.now();
+    const activeSince = params.activeSince ?? (now - TARGET_PARTICIPANT_ACTIVE_WINDOW_MS);
+    const isChannelRoot = !params.threadRootId?.trim();
+    const recentTargetParticipants = listRecentTargetParticipants(db, {
+        channelId: params.channelId,
+        threadRootId: params.threadRootId,
+        activeSince,
+    });
+    const rosterParticipants = listAgentSurfaceRosterParticipants(db, {
+        channelId: params.channelId,
+        threadRootId: params.threadRootId,
+        now,
+    });
+    const merged = mergeParticipants(isChannelRoot ? normalizeRootParticipants(recentTargetParticipants) : recentTargetParticipants, isChannelRoot ? normalizeRootParticipants(rosterParticipants) : rosterParticipants);
+    return isChannelRoot ? merged.slice(0, CHANNEL_ROOT_ROSTER_LIMIT) : merged;
+}
+export function captureUnifiedSurfaceParticipantState(db, params) {
+    const surfaceThreadKey = params.threadRootId?.trim() ?? '';
+    const legacyParticipant = db.prepare(`SELECT role, joined_at as joinedAt, last_active_at as lastActiveAt
+       FROM target_participants
+      WHERE agent_id = ? AND channel_id = ? AND thread_root_id = ?
+      LIMIT 1`).get(params.agentId, params.channelId, surfaceThreadKey);
+    const rosterRows = db.prepare(`SELECT source,
+            source_key as sourceKey,
+            source_agent_id as sourceAgentId,
+            expires_at as expiresAt,
+            created_at as createdAt,
+            updated_at as updatedAt
+       FROM agent_surface_roster
+      WHERE target_agent_id = ?
+        AND channel_id = ?
+        AND surface_thread_key = ?
+        AND source IN ('explicit_mention', 'surface_owner', 'recent_activity')`).all(params.agentId, params.channelId, surfaceThreadKey);
+    return {
+        legacyParticipant: legacyParticipant ?? null,
+        rosterRows,
+    };
+}
+export function restoreUnifiedSurfaceParticipantState(db, params) {
+    const surfaceThreadKey = params.threadRootId?.trim() ?? '';
+    if (params.snapshot.legacyParticipant) {
+        db.prepare(`INSERT INTO target_participants(agent_id, channel_id, thread_root_id, role, joined_at, last_active_at)
+       VALUES(?, ?, ?, ?, ?, ?)
+       ON CONFLICT(agent_id, channel_id, thread_root_id) DO UPDATE SET
+         role = excluded.role,
+         joined_at = excluded.joined_at,
+         last_active_at = excluded.last_active_at`).run(params.agentId, params.channelId, surfaceThreadKey, params.snapshot.legacyParticipant.role, params.snapshot.legacyParticipant.joinedAt, params.snapshot.legacyParticipant.lastActiveAt);
+    }
+    else {
+        db.prepare(`DELETE FROM target_participants
+        WHERE agent_id = ? AND channel_id = ? AND thread_root_id = ?`).run(params.agentId, params.channelId, surfaceThreadKey);
+    }
+    db.prepare(`DELETE FROM agent_surface_roster
+      WHERE target_agent_id = ?
+        AND channel_id = ?
+        AND surface_thread_key = ?
+        AND source IN ('explicit_mention', 'surface_owner', 'recent_activity')`).run(params.agentId, params.channelId, surfaceThreadKey);
+    for (const row of params.snapshot.rosterRows) {
+        db.prepare(`INSERT INTO agent_surface_roster(
+         target_agent_id, channel_id, surface_thread_key, source, source_key, source_agent_id, expires_at, created_at, updated_at
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(params.agentId, params.channelId, surfaceThreadKey, row.source, row.sourceKey, row.sourceAgentId, row.expiresAt, row.createdAt, row.updatedAt);
+    }
+}

package/dist/web/contextBundleRanking.js

@@ -0,0 +1,154 @@
+export const CONTEXT_BUNDLE_WEIGHTS = {
+    surface: {
+        boundTaskMatch: 120,
+        linkedTaskMatch: 90,
+        activeHandoff: 100,
+        recentHandoff: 70,
+        sameThreadRoot: 80,
+        sameTargetFamily: 60,
+        participantOverlap: 24,
+        ownerMatch: 18,
+        rolePresent: 8,
+        unreadActivity: 14,
+        queuedActivity: 18,
+        recentActivity: 10,
+    },
+    task: {
+        boundTaskMatch: 120,
+        linkedTaskMatch: 95,
+        activeHandoff: 80,
+        recentHandoff: 50,
+        sameTargetFamily: 40,
+        taskStatusActive: 20,
+        taskStatusReview: 16,
+        recentActivity: 10,
+    },
+    handoff: {
+        currentConversationHandoff: 120,
+        linkedTaskMatch: 90,
+        activeHandoff: 70,
+        recentHandoff: 30,
+        sameTargetFamily: 40,
+    },
+};
+export const CONTEXT_BUNDLE_RECENT_ACTIVITY_WINDOW_MS = 6 * 60 * 60 * 1000;
+export function scoreSurfaceCandidate(input) {
+    const reasons = [];
+    if (input.hasBoundTaskMatch) {
+        reasons.push(reason('bound_task_match', 'Shares the current bound task', CONTEXT_BUNDLE_WEIGHTS.surface.boundTaskMatch));
+    }
+    if (input.linkedTaskMatches.length > 0) {
+        reasons.push(reason('linked_task_match', 'Linked to the same task context', CONTEXT_BUNDLE_WEIGHTS.surface.linkedTaskMatch, summarizeList(input.linkedTaskMatches)));
+    }
+    if (input.hasActiveHandoff) {
+        reasons.push(reason('active_handoff', 'Has an open handoff relationship', CONTEXT_BUNDLE_WEIGHTS.surface.activeHandoff));
+    }
+    if (input.hasRecentHandoff) {
+        reasons.push(reason('recent_handoff', 'Recently involved in a handoff', CONTEXT_BUNDLE_WEIGHTS.surface.recentHandoff));
+    }
+    if (input.isSameThreadRoot) {
+        reasons.push(reason('same_thread_root', 'Same thread root family', CONTEXT_BUNDLE_WEIGHTS.surface.sameThreadRoot));
+    }
+    if (input.isSameTargetFamily) {
+        reasons.push(reason('same_target_family', 'Same target family', CONTEXT_BUNDLE_WEIGHTS.surface.sameTargetFamily));
+    }
+    if (input.participantOverlapCount > 0) {
+        reasons.push(reason('participant_overlap', 'Shares recent participants', CONTEXT_BUNDLE_WEIGHTS.surface.participantOverlap, `overlap=${input.participantOverlapCount}`));
+    }
+    if (input.ownerMatch) {
+        reasons.push(reason('owner_match', 'Same owner context', CONTEXT_BUNDLE_WEIGHTS.surface.ownerMatch));
+    }
+    if (input.hasRole) {
+        reasons.push(reason('role_present', 'Has an explicit agent role', CONTEXT_BUNDLE_WEIGHTS.surface.rolePresent));
+    }
+    if (input.unreadCount > 0) {
+        reasons.push(reason('unread_activity', 'Unread activity is waiting', CONTEXT_BUNDLE_WEIGHTS.surface.unreadActivity, `unread=${input.unreadCount}`));
+    }
+    if (input.queuedPromptCount > 0) {
+        reasons.push(reason('queued_activity', 'Queued prompts are waiting', CONTEXT_BUNDLE_WEIGHTS.surface.queuedActivity, `queued=${input.queuedPromptCount}`));
+    }
+    if (isRecentlyUpdated(input.updatedAt, input.nowMs)) {
+        reasons.push(reason('recent_activity', 'Updated recently', CONTEXT_BUNDLE_WEIGHTS.surface.recentActivity));
+    }
+    return { score: sumReasons(reasons), reasons };
+}
+export function scoreTaskCandidate(input) {
+    const reasons = [];
+    if (input.hasBoundTaskMatch) {
+        reasons.push(reason('bound_task_match', 'Matches the current bound task', CONTEXT_BUNDLE_WEIGHTS.task.boundTaskMatch));
+    }
+    if (input.linkedTaskMatches.length > 0) {
+        reasons.push(reason('linked_task_match', 'Linked to the same task context', CONTEXT_BUNDLE_WEIGHTS.task.linkedTaskMatch, summarizeList(input.linkedTaskMatches)));
+    }
+    if (input.hasActiveHandoff) {
+        reasons.push(reason('active_handoff', 'Referenced by an open handoff', CONTEXT_BUNDLE_WEIGHTS.task.activeHandoff));
+    }
+    if (input.hasRecentHandoff) {
+        reasons.push(reason('recent_handoff', 'Referenced by a recent handoff', CONTEXT_BUNDLE_WEIGHTS.task.recentHandoff));
+    }
+    if (input.isSameTargetFamily) {
+        reasons.push(reason('same_target_family', 'Lives on the same target family', CONTEXT_BUNDLE_WEIGHTS.task.sameTargetFamily));
+    }
+    if (input.status === 'in_progress') {
+        reasons.push(reason('task_status_active', 'Task is actively in progress', CONTEXT_BUNDLE_WEIGHTS.task.taskStatusActive));
+    }
+    if (input.status === 'in_review') {
+        reasons.push(reason('task_status_review', 'Task is waiting in review', CONTEXT_BUNDLE_WEIGHTS.task.taskStatusReview));
+    }
+    if (isRecentlyUpdated(input.updatedAt, input.nowMs)) {
+        reasons.push(reason('recent_activity', 'Updated recently', CONTEXT_BUNDLE_WEIGHTS.task.recentActivity));
+    }
+    return { score: sumReasons(reasons), reasons };
+}
+export function scoreHandoffCandidate(input) {
+    const reasons = [];
+    if (input.matchesCurrentConversation) {
+        reasons.push(reason('current_conversation_handoff', 'Directly tied to the current conversation', CONTEXT_BUNDLE_WEIGHTS.handoff.currentConversationHandoff));
+    }
+    if (input.hasRelatedTaskMatch) {
+        reasons.push(reason('linked_task_match', 'Shares the current task context', CONTEXT_BUNDLE_WEIGHTS.handoff.linkedTaskMatch));
+    }
+    if (input.status === 'started' || input.status === 'accepted') {
+        reasons.push(reason('active_handoff', 'Handoff is still open', CONTEXT_BUNDLE_WEIGHTS.handoff.activeHandoff));
+    }
+    else if (isRecentlyUpdated(input.updatedAt, input.nowMs)) {
+        reasons.push(reason('recent_handoff', 'Handoff changed recently', CONTEXT_BUNDLE_WEIGHTS.handoff.recentHandoff));
+    }
+    if (input.isSameTargetFamily) {
+        reasons.push(reason('same_target_family', 'Touches the same target family', CONTEXT_BUNDLE_WEIGHTS.handoff.sameTargetFamily));
+    }
+    return { score: sumReasons(reasons), reasons };
+}
+export function compareRankedItems(left, right) {
+    if (right.score !== left.score)
+        return right.score - left.score;
+    const leftTime = Date.parse(left.updatedAt);
+    const rightTime = Date.parse(right.updatedAt);
+    if (Number.isFinite(leftTime) && Number.isFinite(rightTime) && rightTime !== leftTime) {
+        return rightTime - leftTime;
+    }
+    return 0;
+}
+export function isRecentlyUpdated(updatedAt, nowMs = Date.now()) {
+    const updatedAtMs = Date.parse(updatedAt);
+    if (!Number.isFinite(updatedAtMs))
+        return false;
+    return nowMs - updatedAtMs <= CONTEXT_BUNDLE_RECENT_ACTIVITY_WINDOW_MS;
+}
+function reason(code, label, weight, detail) {
+    return {
+        code,
+        label,
+        weight,
+        ...(detail ? { detail } : {}),
+    };
+}
+function sumReasons(reasons) {
+    return reasons.reduce((sum, item) => sum + item.weight, 0);
+}
+function summarizeList(values) {
+    const filtered = values.map((value) => value.trim()).filter(Boolean);
+    if (filtered.length === 0)
+        return null;
+    return filtered.slice(0, 3).join(', ');
+}