@bbigbang/core 0.1.0

package/dist/web/conversationHandoffs.js

@@ -0,0 +1,612 @@
+import { randomUUID } from 'node:crypto';
+import { createPromptContextSection, } from './promptContextSections.js';
+export function createConversationHandoff(db, params) {
+    const handoffId = randomUUID();
+    const now = Date.now();
+    const payload = normalizeConversationHandoffPayload(params.payload);
+    db.prepare(`INSERT INTO conversation_handoffs(
+       handoff_id,
+       agent_id,
+       source_conversation_id,
+       target_conversation_id,
+       target_reply_target,
+       workflow_kind,
+       source_disposition,
+       task_id,
+       task_number,
+       mode,
+       payload_json,
+       status,
+       created_at,
+       updated_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(handoffId, params.agentId, params.sourceConversationId, params.targetConversationId ?? null, params.targetReplyTarget, params.workflowKind ?? 'generic', params.sourceDisposition ?? (params.mode === 'continue_there' ? 'cancel_current_run' : 'keep_running'), params.taskId ?? null, params.taskNumber ?? null, params.mode, JSON.stringify(payload), params.status, now, now);
+    return {
+        handoffId,
+        agentId: params.agentId,
+        sourceConversationId: params.sourceConversationId,
+        targetConversationId: params.targetConversationId ?? null,
+        targetReplyTarget: params.targetReplyTarget,
+        workflowKind: params.workflowKind ?? 'generic',
+        sourceDisposition: params.sourceDisposition ?? (params.mode === 'continue_there' ? 'cancel_current_run' : 'keep_running'),
+        taskId: params.taskId ?? null,
+        taskNumber: typeof params.taskNumber === 'number' ? Math.floor(params.taskNumber) : null,
+        mode: params.mode,
+        status: params.status,
+        payload,
+        createdAt: new Date(now).toISOString(),
+        updatedAt: new Date(now).toISOString(),
+    };
+}
+export function markConversationHandoffAccepted(db, params) {
+    return updateLatestOpenConversationHandoff(db, {
+        targetConversationId: params.targetConversationId,
+        targetRunId: params.targetRunId,
+        status: 'accepted',
+        payload: {
+            targetRunId: params.targetRunId,
+            error: null,
+        },
+    });
+}
+export function markConversationHandoffCompleted(db, params) {
+    return updateLatestOpenConversationHandoff(db, {
+        targetConversationId: params.targetConversationId,
+        targetRunId: params.targetRunId ?? null,
+        status: 'completed',
+        payload: {
+            ...(params.targetRunId ? { targetRunId: params.targetRunId } : {}),
+            completionMessageId: params.completionMessageId ?? null,
+            error: null,
+        },
+    });
+}
+export function markConversationHandoffCancelled(db, params) {
+    return updateLatestOpenConversationHandoff(db, {
+        targetConversationId: params.targetConversationId,
+        targetRunId: params.targetRunId ?? null,
+        status: 'cancelled',
+        payload: {
+            ...(params.targetRunId ? { targetRunId: params.targetRunId } : {}),
+            error: params.error ?? null,
+        },
+    });
+}
+export function markConversationHandoffFailed(db, params) {
+    return updateLatestOpenConversationHandoff(db, {
+        targetConversationId: params.targetConversationId,
+        targetRunId: params.targetRunId ?? null,
+        status: 'failed',
+        payload: {
+            ...(params.targetRunId ? { targetRunId: params.targetRunId } : {}),
+            ...(params.error ? { error: params.error } : {}),
+        },
+    });
+}
+export function markConversationHandoffSourceCancelled(db, params) {
+    const row = db.prepare(`SELECT handoff_id as handoffId,
+            agent_id as agentId,
+            source_conversation_id as sourceConversationId,
+            target_conversation_id as targetConversationId,
+            target_reply_target as targetReplyTarget,
+            workflow_kind as workflowKind,
+            source_disposition as sourceDisposition,
+            task_id as taskId,
+            task_number as taskNumber,
+            mode,
+            status,
+            payload_json as payloadJson,
+            created_at as createdAt,
+            updated_at as updatedAt
+       FROM conversation_handoffs
+      WHERE handoff_id = ?
+      LIMIT 1`).get(params.handoffId);
+    if (!row)
+        return null;
+    const record = mapConversationHandoffRow(row);
+    const now = Date.now();
+    const payload = normalizeConversationHandoffPayload({
+        ...record.payload,
+        cancelRunId: params.cancelRunId,
+        goal: record.payload.goal,
+    });
+    db.prepare(`UPDATE conversation_handoffs
+        SET payload_json = ?,
+            updated_at = ?
+      WHERE handoff_id = ?`).run(JSON.stringify(payload), now, params.handoffId);
+    return {
+        ...record,
+        payload,
+        updatedAt: new Date(now).toISOString(),
+    };
+}
+export function listRecentConversationHandoffs(db, agentId, limit = 5) {
+    const safeLimit = Math.max(1, Math.min(limit, 10));
+    const rows = db.prepare(`SELECT handoff_id as handoffId,
+            agent_id as agentId,
+            source_conversation_id as sourceConversationId,
+            target_conversation_id as targetConversationId,
+            target_reply_target as targetReplyTarget,
+            workflow_kind as workflowKind,
+            source_disposition as sourceDisposition,
+            task_id as taskId,
+            task_number as taskNumber,
+            mode,
+            status,
+            payload_json as payloadJson,
+            created_at as createdAt,
+            updated_at as updatedAt
+       FROM conversation_handoffs
+      WHERE agent_id = ?
+      ORDER BY updated_at DESC, created_at DESC
+      LIMIT ?`).all(agentId, safeLimit);
+    return rows.map(mapConversationHandoffRow);
+}
+export function getConversationHandoffById(db, handoffId) {
+    const row = db.prepare(`SELECT handoff_id as handoffId,
+            agent_id as agentId,
+            source_conversation_id as sourceConversationId,
+            target_conversation_id as targetConversationId,
+            target_reply_target as targetReplyTarget,
+            workflow_kind as workflowKind,
+            source_disposition as sourceDisposition,
+            task_id as taskId,
+            task_number as taskNumber,
+            mode,
+            status,
+            payload_json as payloadJson,
+            created_at as createdAt,
+            updated_at as updatedAt
+       FROM conversation_handoffs
+      WHERE handoff_id = ?
+      LIMIT 1`).get(handoffId);
+    return row ? mapConversationHandoffRow(row) : null;
+}
+export function getHandoffState(db, handoffId) {
+    const record = getConversationHandoffById(db, handoffId);
+    if (!record)
+        return null;
+    const runRows = db.prepare(`SELECT run_id as runId,
+            agent_id as agentId,
+            disposition,
+            created_at as createdAt,
+            completed_at as completedAt
+       FROM handoff_runs
+      WHERE handoff_id = ?
+      ORDER BY created_at DESC`).all(handoffId);
+    const runs = runRows.map((row) => ({
+        runId: row.runId,
+        agentId: row.agentId,
+        disposition: row.disposition,
+        createdAt: new Date(row.createdAt).toISOString(),
+        completedAt: row.completedAt ? new Date(row.completedAt).toISOString() : null,
+    }));
+    return { ...record, runs };
+}
+export function insertHandoffRun(db, params) {
+    const handoffExists = db.prepare(`SELECT 1 FROM conversation_handoffs WHERE handoff_id = ? LIMIT 1`).get(params.handoffId);
+    if (!handoffExists)
+        return null;
+    const now = Date.now();
+    // Mark previous non-completed runs for this handoff as completed
+    db.prepare(`UPDATE handoff_runs
+        SET completed_at = ?
+      WHERE handoff_id = ?
+        AND completed_at IS NULL`).run(now, params.handoffId);
+    const id = randomUUID();
+    db.prepare(`INSERT INTO handoff_runs(id, handoff_id, run_id, agent_id, disposition, created_at)
+     VALUES(?, ?, ?, ?, ?, ?)`).run(id, params.handoffId, params.runId, params.agentId, params.disposition, now);
+    return {
+        runId: params.runId,
+        agentId: params.agentId,
+        disposition: params.disposition,
+        createdAt: new Date(now).toISOString(),
+        completedAt: null,
+    };
+}
+export function getLatestConversationHandoffForConversation(db, params) {
+    const row = db.prepare(`SELECT handoff_id as handoffId,
+            agent_id as agentId,
+            source_conversation_id as sourceConversationId,
+            target_conversation_id as targetConversationId,
+            target_reply_target as targetReplyTarget,
+            workflow_kind as workflowKind,
+            source_disposition as sourceDisposition,
+            task_id as taskId,
+            task_number as taskNumber,
+            mode,
+            status,
+            payload_json as payloadJson,
+            created_at as createdAt,
+            updated_at as updatedAt
+       FROM conversation_handoffs
+      WHERE (source_conversation_id = ? OR target_conversation_id = ?)
+        ${params.openOnly ? `AND status IN ('started', 'accepted')` : ''}
+      ORDER BY updated_at DESC, created_at DESC
+      LIMIT 1`).get(params.conversationId, params.conversationId);
+    return row ? mapConversationHandoffRow(row) : null;
+}
+export function formatConversationHandoff(record) {
+    const summary = summarizeText(record.payload.goal, 120) ?? '(missing goal)';
+    const source = record.payload.sourceTarget?.trim() || record.sourceConversationId;
+    const error = record.payload.error?.trim();
+    const failure = error ? ` error=${summarizeText(error, 100)}` : '';
+    const workflow = record.workflowKind === 'generic' ? record.mode : `${record.workflowKind}/${record.mode}`;
+    const task = record.taskNumber ? ` task=#${record.taskNumber}` : '';
+    return `${workflow} [${record.status}] ${source} -> ${record.targetReplyTarget}${task} goal=${summary}${failure}`;
+}
+function buildContinueThereSourceReminderLines(params) {
+    const lines = [
+        `Detailed execution intentionally moved from ${params.sourceReplyTarget} to ${params.targetReplyTarget}.`,
+        'This was a normal platform handoff, not a user interruption, runtime failure, or accidental cancellation.',
+    ];
+    if (params.relatedTaskRef?.trim()) {
+        lines.push(`Related task: ${params.relatedTaskRef.trim()}`);
+    }
+    lines.push(`If you are later asked about this from ${params.sourceReplyTarget}, describe it as a normal handoff/continue-there transition to ${params.targetReplyTarget}.`, 'Do not say that the earlier work on this surface was interrupted or cut off.', `If you need to report progress or status later, inspect ${params.targetReplyTarget} or structured task/handoff state first instead of relying on this source surface's pre-handoff plan.`);
+    return lines;
+}
+export function buildContinueThereSourceNoticePrompt(params) {
+    return [
+        '[System handoff notice]',
+        ...buildContinueThereSourceReminderLines(params),
+        `Stop detailed execution on ${params.sourceReplyTarget} now; it continues on ${params.targetReplyTarget}.`,
+    ].join('\n');
+}
+export function buildSourceSurfaceHandoffReminderSection(db, params) {
+    const conversation = resolveSourceSurfaceConversation(db, params);
+    if (!conversation?.replyTarget)
+        return null;
+    const handoff = loadLatestContinueThereSourceHandoff(db, conversation.conversationId);
+    if (!handoff)
+        return null;
+    if (hasLaterAgentVisibleMessageOnSurface(db, conversation, handoff.createdAt))
+        return null;
+    return createPromptContextSection('source_handoff_reminder', [
+        '[Source-surface handoff reminder]',
+        ...buildContinueThereSourceReminderLines({
+            sourceReplyTarget: conversation.replyTarget,
+            targetReplyTarget: handoff.targetReplyTarget,
+            relatedTaskRef: handoff.payload.relatedTaskRef,
+        }),
+    ].join('\n'));
+}
+export function buildConversationHandoffCapsuleText(params) {
+    const lines = [
+        '[Handoff capsule]',
+        'This is a must-keep execution-context block for the current handoff target.',
+        '',
+        '[Handoff metadata]',
+        `mode: ${params.mode}`,
+        `reply_target: ${params.targetReplyTarget}`,
+    ];
+    if (params.payload.sourceTarget) {
+        lines.push(`source_target: ${params.payload.sourceTarget}`);
+    }
+    lines.push('', '[Goal]', params.payload.goal);
+    if (params.payload.whyNow) {
+        lines.push('', '[Why now]', params.payload.whyNow);
+    }
+    if (params.payload.alreadyDone.length > 0) {
+        lines.push('', '[Already done]', ...params.payload.alreadyDone.map((item) => `- ${item}`));
+    }
+    if (params.payload.expectedOutput) {
+        lines.push('', '[Expected output]', params.payload.expectedOutput);
+    }
+    if (params.payload.relatedTaskRef) {
+        lines.push('', '[Related task]', params.payload.relatedTaskRef);
+    }
+    if (params.payload.sourceSummary) {
+        lines.push('', '[Source surface summary]', params.payload.sourceSummary);
+    }
+    if (params.payload.sourceRollingSummary) {
+        lines.push('', '[Recent dialogue rolling summary]', params.payload.sourceRollingSummary);
+    }
+    if (params.payload.sourceContext) {
+        const lastUserMsg = summarizeText(params.payload.sourceContext.lastUserMessage, 500);
+        if (lastUserMsg) {
+            lines.push('', '[Source last user message]', lastUserMsg);
+        }
+        const lastAgentMsg = summarizeText(params.payload.sourceContext.lastAgentMessage, 500);
+        if (lastAgentMsg) {
+            lines.push('', '[Source last agent message]', lastAgentMsg);
+        }
+        if (!params.payload.sourceSummary
+            && (params.payload.sourceContext.boundTaskRef
+                || params.payload.sourceContext.boundTaskTitle
+                || params.payload.sourceContext.ownerName
+                || params.payload.sourceContext.myRole
+                || params.payload.sourceContext.participants.length > 0)) {
+            lines.push('', '[Source surface context]');
+            if (params.payload.sourceContext.boundTaskRef || params.payload.sourceContext.boundTaskTitle) {
+                lines.push(`bound_task: ${params.payload.sourceContext.boundTaskRef ?? '(no task ref)'}${params.payload.sourceContext.boundTaskTitle ? ` — ${params.payload.sourceContext.boundTaskTitle}` : ''}`);
+            }
+            if (params.payload.sourceContext.myRole) {
+                lines.push(`my_role: ${params.payload.sourceContext.myRole}`);
+            }
+            if (params.payload.sourceContext.ownerName) {
+                lines.push(`owner: @${params.payload.sourceContext.ownerName}`);
+            }
+            if (params.payload.sourceContext.participants.length > 0) {
+                lines.push(`participants: ${params.payload.sourceContext.participants.map((name) => `@${name}`).join(', ')}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+export function buildConversationHandoffPrompt(params) {
+    const lines = [
+        '[Conversation handoff]',
+        'You are the same agent continuing work on another surface.',
+        '',
+        'The full handoff capsule is attached in activation/resume context so it survives queueing and restore.',
+    ];
+    if (params.payload.constraints.length > 0) {
+        lines.push('', '[Constraints]', ...params.payload.constraints.map((item) => `- ${item}`));
+    }
+    if (params.payload.optionalRefs.length > 0) {
+        lines.push('', '[Optional refs]', ...params.payload.optionalRefs.map((item) => `- ${item}`));
+    }
+    lines.push('', 'Rules:');
+    lines.push('- This handoff comes from another work surface of the same agent identity.');
+    if (params.mode === 'continue_there') {
+        lines.push('- Detailed execution should continue here. Treat the source surface as handed off.');
+    }
+    else if (params.mode === 'delegate_only') {
+        lines.push('- Handle the delegated follow-up here. The source surface may still remain active.');
+    }
+    else {
+        lines.push('- Coordinate through summaries and explicit handoffs; avoid duplicating the same work across surfaces.');
+    }
+    lines.push('- Prefer this target for detailed work that belongs here.');
+    lines.push('- Choose the status command by question: bigbang self state for global surface overview, bigbang runtime presence for node/host/runtime facts, bigbang workspace inspect for current workspace git/directory facts, bigbang conversation list for bulk surface discovery, bigbang conversation summary for one known surface, and bigbang context bundle only to shortlist related surfaces/tasks/handoffs before deeper inspection or another handoff.');
+    return lines.join('\n');
+}
+function normalizeConversationHandoffPayload(payload) {
+    return {
+        goal: normalizeRequiredText(payload.goal) ?? '(missing goal)',
+        whyNow: summarizeText(payload.whyNow, 400),
+        constraints: normalizeStringList(payload.constraints),
+        alreadyDone: normalizeStringList(payload.alreadyDone),
+        expectedOutput: summarizeText(payload.expectedOutput, 400),
+        sourceTarget: summarizeText(payload.sourceTarget, 200),
+        relatedTaskRef: summarizeText(payload.relatedTaskRef, 120),
+        optionalRefs: normalizeStringList(payload.optionalRefs),
+        sourceSummary: summarizeText(payload.sourceSummary, 1200),
+        sourceRollingSummary: summarizeText(payload.sourceRollingSummary, 1200),
+        targetRunId: summarizeText(payload.targetRunId, 160),
+        cancelRunId: summarizeText(payload.cancelRunId, 160),
+        completionMessageId: summarizeText(payload.completionMessageId, 160),
+        error: summarizeText(payload.error, 400),
+        sourceContext: payload.sourceContext
+            ? {
+                lastUserMessage: summarizeText(payload.sourceContext.lastUserMessage, 280),
+                lastAgentMessage: summarizeText(payload.sourceContext.lastAgentMessage, 280),
+                boundTaskRef: summarizeText(payload.sourceContext.boundTaskRef, 160),
+                boundTaskTitle: summarizeText(payload.sourceContext.boundTaskTitle, 200),
+                ownerName: summarizeText(payload.sourceContext.ownerName, 160),
+                participants: normalizeStringList(payload.sourceContext.participants),
+                myRole: summarizeText(payload.sourceContext.myRole, 120),
+            }
+            : null,
+    };
+}
+function parseConversationHandoffPayload(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return normalizeConversationHandoffPayload({
+            goal: typeof parsed?.goal === 'string' ? parsed.goal : '(missing goal)',
+            whyNow: typeof parsed?.whyNow === 'string' ? parsed.whyNow : null,
+            constraints: Array.isArray(parsed?.constraints) ? parsed.constraints : [],
+            alreadyDone: Array.isArray(parsed?.alreadyDone) ? parsed.alreadyDone : [],
+            expectedOutput: typeof parsed?.expectedOutput === 'string' ? parsed.expectedOutput : null,
+            sourceTarget: typeof parsed?.sourceTarget === 'string' ? parsed.sourceTarget : null,
+            relatedTaskRef: typeof parsed?.relatedTaskRef === 'string' ? parsed.relatedTaskRef : null,
+            optionalRefs: Array.isArray(parsed?.optionalRefs) ? parsed.optionalRefs : [],
+            sourceSummary: typeof parsed?.sourceSummary === 'string' ? parsed.sourceSummary : null,
+            sourceRollingSummary: typeof parsed?.sourceRollingSummary === 'string' ? parsed.sourceRollingSummary : null,
+            targetRunId: typeof parsed?.targetRunId === 'string' ? parsed.targetRunId : null,
+            cancelRunId: typeof parsed?.cancelRunId === 'string' ? parsed.cancelRunId : null,
+            completionMessageId: typeof parsed?.completionMessageId === 'string' ? parsed.completionMessageId : null,
+            error: typeof parsed?.error === 'string' ? parsed.error : null,
+            sourceContext: parsed?.sourceContext && typeof parsed.sourceContext === 'object'
+                ? {
+                    lastUserMessage: typeof parsed.sourceContext.lastUserMessage === 'string' ? parsed.sourceContext.lastUserMessage : null,
+                    lastAgentMessage: typeof parsed.sourceContext.lastAgentMessage === 'string' ? parsed.sourceContext.lastAgentMessage : null,
+                    boundTaskRef: typeof parsed.sourceContext.boundTaskRef === 'string' ? parsed.sourceContext.boundTaskRef : null,
+                    boundTaskTitle: typeof parsed.sourceContext.boundTaskTitle === 'string' ? parsed.sourceContext.boundTaskTitle : null,
+                    ownerName: typeof parsed.sourceContext.ownerName === 'string' ? parsed.sourceContext.ownerName : null,
+                    participants: Array.isArray(parsed.sourceContext.participants) ? parsed.sourceContext.participants : [],
+                    myRole: typeof parsed.sourceContext.myRole === 'string' ? parsed.sourceContext.myRole : null,
+                }
+                : null,
+        });
+    }
+    catch {
+        return normalizeConversationHandoffPayload({ goal: '(missing goal)' });
+    }
+}
+function resolveSourceSurfaceConversation(db, params) {
+    const normalizedThreadRootId = params.threadRootId?.trim() || '';
+    if (params.replyTarget.startsWith('dm:@')) {
+        const row = db.prepare(`SELECT id as conversationId,
+              agent_id as agentId,
+              channel_id as channelId,
+              reply_target as replyTarget,
+              thread_kind as threadKind,
+              thread_root_id as threadRootId
+         FROM conversations
+        WHERE agent_id = ?
+          AND thread_kind = 'direct'
+          AND reply_target = ?
+          AND COALESCE(thread_root_id, '') = ?
+        ORDER BY updated_at DESC
+        LIMIT 1`).get(params.agentId, params.replyTarget, normalizedThreadRootId);
+        return row ?? null;
+    }
+    const row = db.prepare(`SELECT id as conversationId,
+            agent_id as agentId,
+            channel_id as channelId,
+            reply_target as replyTarget,
+            thread_kind as threadKind,
+            thread_root_id as threadRootId
+       FROM conversations
+      WHERE agent_id = ?
+        AND thread_kind = 'branch'
+        AND channel_id = ?
+        AND reply_target = ?
+        AND COALESCE(thread_root_id, '') = ?
+      ORDER BY updated_at DESC
+      LIMIT 1`).get(params.agentId, params.channelId, params.replyTarget, normalizedThreadRootId);
+    return row ?? null;
+}
+function loadLatestContinueThereSourceHandoff(db, sourceConversationId) {
+    const row = db.prepare(`SELECT handoff_id as handoffId,
+            agent_id as agentId,
+            source_conversation_id as sourceConversationId,
+            target_conversation_id as targetConversationId,
+            target_reply_target as targetReplyTarget,
+            workflow_kind as workflowKind,
+            source_disposition as sourceDisposition,
+            task_id as taskId,
+            task_number as taskNumber,
+            h.mode as mode,
+            h.status as status,
+            h.payload_json as payloadJson,
+            h.created_at as createdAt,
+            h.updated_at as updatedAt
+       FROM conversation_handoffs h
+      WHERE h.source_conversation_id = ?
+        AND h.mode = 'continue_there'
+        AND h.source_disposition = 'cancel_current_run'
+      ORDER BY created_at DESC, updated_at DESC
+      LIMIT 1`).get(sourceConversationId);
+    if (!row)
+        return null;
+    const handoff = mapConversationHandoffRow(row);
+    if (handoff.status !== 'failed')
+        return handoff;
+    if (handoff.payload.cancelRunId)
+        return handoff;
+    const legacyCancelledEvent = db.prepare(`SELECT 1 as found
+       FROM events e
+      WHERE json_extract(e.payload_json, '$.kind') = 'conversation_handoff'
+        AND json_extract(e.payload_json, '$.handoffId') = ?
+        AND json_extract(e.payload_json, '$.cancelRunId') IS NOT NULL
+      LIMIT 1`).get(handoff.handoffId);
+    return legacyCancelledEvent ? handoff : null;
+}
+function hasLaterAgentVisibleMessageOnSurface(db, conversation, createdAtIso) {
+    const createdAtMs = Date.parse(createdAtIso);
+    if (!Number.isFinite(createdAtMs))
+        return false;
+    const messageChannelId = conversation.threadKind === 'direct'
+        ? `dm:${conversation.agentId ?? ''}`
+        : conversation.channelId;
+    if (!messageChannelId || !conversation.replyTarget)
+        return false;
+    const row = db.prepare(`SELECT 1
+       FROM channel_messages
+      WHERE channel_id = ?
+        AND target = ?
+        AND sender_type = 'agent'
+        AND COALESCE(thread_root_id, '') = ?
+        AND created_at > ?
+      ORDER BY created_at DESC, seq DESC
+      LIMIT 1`).get(messageChannelId, conversation.replyTarget, conversation.threadRootId ?? '', createdAtMs);
+    return Boolean(row);
+}
+function updateLatestOpenConversationHandoff(db, params) {
+    const record = findLatestOpenConversationHandoff(db, params.targetConversationId, params.targetRunId ?? null);
+    if (!record)
+        return null;
+    const now = Date.now();
+    const payload = normalizeConversationHandoffPayload({
+        ...record.payload,
+        ...params.payload,
+        goal: params.payload?.goal ?? record.payload.goal,
+    });
+    db.prepare(`UPDATE conversation_handoffs
+        SET target_conversation_id = ?,
+            payload_json = ?,
+            status = ?,
+            updated_at = ?
+      WHERE handoff_id = ?`).run(record.targetConversationId ?? params.targetConversationId, JSON.stringify(payload), params.status, now, record.handoffId);
+    return {
+        ...record,
+        targetConversationId: record.targetConversationId ?? params.targetConversationId,
+        status: params.status,
+        payload,
+        updatedAt: new Date(now).toISOString(),
+    };
+}
+function findLatestOpenConversationHandoff(db, targetConversationId, targetRunId) {
+    const rows = db.prepare(`SELECT handoff_id as handoffId,
+            agent_id as agentId,
+            source_conversation_id as sourceConversationId,
+            target_conversation_id as targetConversationId,
+            target_reply_target as targetReplyTarget,
+            workflow_kind as workflowKind,
+            source_disposition as sourceDisposition,
+            task_id as taskId,
+            task_number as taskNumber,
+            mode,
+            status,
+            payload_json as payloadJson,
+            created_at as createdAt,
+            updated_at as updatedAt
+       FROM conversation_handoffs
+      WHERE target_conversation_id = ?
+        AND status IN ('started', 'accepted')
+      ORDER BY updated_at DESC, created_at DESC
+      LIMIT 12`).all(targetConversationId);
+    const records = rows.map(mapConversationHandoffRow);
+    if (targetRunId) {
+        const exact = records.find((record) => record.payload.targetRunId === targetRunId);
+        if (exact)
+            return exact;
+        const pending = records.find((record) => !record.payload.targetRunId);
+        if (pending)
+            return pending;
+    }
+    return records[0] ?? null;
+}
+function mapConversationHandoffRow(row) {
+    return {
+        handoffId: row.handoffId,
+        agentId: row.agentId,
+        sourceConversationId: row.sourceConversationId,
+        targetConversationId: row.targetConversationId ?? null,
+        targetReplyTarget: row.targetReplyTarget,
+        workflowKind: row.workflowKind,
+        sourceDisposition: row.sourceDisposition,
+        taskId: row.taskId ?? null,
+        taskNumber: typeof row.taskNumber === 'number' ? Math.floor(row.taskNumber) : null,
+        mode: row.mode,
+        status: row.status,
+        payload: parseConversationHandoffPayload(row.payloadJson),
+        createdAt: new Date(row.createdAt).toISOString(),
+        updatedAt: new Date(row.updatedAt).toISOString(),
+    };
+}
+function normalizeRequiredText(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+function normalizeStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => summarizeText(item, 300))
+        .filter((item) => Boolean(item));
+}
+function summarizeText(value, limit) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return null;
+    return normalized.length > limit ? `${normalized.slice(0, limit - 3)}...` : normalized;
+}