@bbigbang/core 0.1.0

package/dist/web/sameAgentHandoffs.js

@@ -0,0 +1,494 @@
+import { randomUUID } from 'node:crypto';
+import { log } from '@bbigbang/runtime-acp';
+import { buildChannelSurfaceActivationEnvelope, buildDirectSurfaceActivationEnvelope } from './activationContext.js';
+import { getUnifiedSurfaceUnreadCheckpoint } from './collaborationSurfaceState.js';
+import { resolveDefaultReplyTarget } from './conversationTargets.js';
+import { advanceAgentSurfaceNotificationAck } from './notificationRounds.js';
+import { buildContinueThereSourceNoticePrompt, buildConversationHandoffCapsuleText, buildConversationHandoffPrompt, createConversationHandoff, markConversationHandoffSourceCancelled, } from './conversationHandoffs.js';
+import { createPromptContextSection, } from './promptContextSections.js';
+import { combinePromptSections } from './workspaceMemoryHints.js';
+function resolveHandoffTargetSurfaceFromConversation(params) {
+    const conversation = params.conversationManager.getConversation(params.targetConversationId);
+    if (!conversation?.agentId)
+        return null;
+    const replyTarget = (params.fallbackReplyTarget ?? conversation.replyTarget ?? '').trim();
+    const channelId = conversation.threadKind === 'direct'
+        ? `dm:${conversation.agentId}`
+        : conversation.channelId;
+    if (!replyTarget || !channelId)
+        return null;
+    return {
+        agentId: conversation.agentId,
+        channelId,
+        replyTarget,
+        threadRootId: conversation.threadRootId ?? null,
+    };
+}
+function loadHandoffTargetSurfaceCheckpointSeedSeq(db, surface) {
+    if (getUnifiedSurfaceUnreadCheckpoint(db, {
+        agentId: surface.agentId,
+        channelId: surface.channelId,
+        threadRootId: surface.threadRootId,
+    }) > 0) {
+        return null;
+    }
+    const isDirectThreadTarget = surface.threadRootId !== null && surface.replyTarget.startsWith('dm:@');
+    const threadClause = surface.threadRootId == null
+        ? 'thread_root_id IS NULL'
+        : isDirectThreadTarget
+            ? '(thread_root_id = ? OR thread_root_id IS NULL)'
+            : 'thread_root_id = ?';
+    const threadArgs = surface.threadRootId == null ? [] : [surface.threadRootId];
+    const row = db.prepare(`SELECT COALESCE(MAX(seq), 0) as maxSeq
+     FROM channel_messages
+     WHERE channel_id = ?
+       AND ${threadClause}`).get(surface.channelId, ...threadArgs);
+    const maxSeq = Math.max(0, Math.floor(Number(row?.maxSeq ?? 0)));
+    return maxSeq > 0 ? maxSeq : null;
+}
+function persistHandoffTargetSurfaceCheckpointSeedIfUnset(db, surface, seedSeq) {
+    if (!surface || seedSeq == null)
+        return;
+    const normalizedSeedSeq = Math.max(0, Math.floor(seedSeq));
+    if (normalizedSeedSeq <= 0)
+        return;
+    if (getUnifiedSurfaceUnreadCheckpoint(db, {
+        agentId: surface.agentId,
+        channelId: surface.channelId,
+        threadRootId: surface.threadRootId,
+    }) > 0) {
+        return;
+    }
+    advanceAgentSurfaceNotificationAck(db, {
+        targetAgentId: surface.agentId,
+        channelId: surface.channelId,
+        threadRootId: surface.threadRootId,
+        ackedThroughSeq: normalizedSeedSeq,
+    });
+}
+export async function performSameAgentHandoff(params) {
+    const sourceDisposition = params.sourceDisposition ?? (params.mode === 'continue_there' ? 'cancel_current_run' : 'keep_running');
+    const failureSourceDisposition = params.failureSourceDisposition ?? 'keep_running';
+    const workflowKind = params.workflowKind ?? 'generic';
+    const targetSurface = resolveHandoffTargetSurfaceFromConversation({
+        conversationManager: params.conversationManager,
+        targetConversationId: params.targetConversationId,
+        fallbackReplyTarget: params.targetReplyTarget,
+    });
+    const safeInvokeLifecycleCallback = (callbackName, callback) => {
+        if (!callback)
+            return;
+        try {
+            callback();
+        }
+        catch (error) {
+            log.warn('[same-agent-handoff] lifecycle callback failed', {
+                callbackName,
+                sourceConversationId: params.sourceConversationId,
+                targetConversationId: params.targetConversationId,
+                targetReplyTarget: params.targetReplyTarget,
+                workflowKind,
+                mode: params.mode,
+                error: String(error?.message ?? error),
+            });
+        }
+    };
+    const cancelSourceRun = async (disposition, options) => {
+        if (disposition !== 'cancel_current_run' || !params.sourceConversationRunId) {
+            return { cancelRequested: false };
+        }
+        if (options?.sendContinueThereNotice && params.mode === 'continue_there') {
+            await params.conversationManager.sendBestEffortSystemNoticeToActiveRun({
+                conversationId: params.sourceConversationId,
+                runId: params.sourceConversationRunId,
+                promptText: buildContinueThereSourceNoticePrompt({
+                    sourceReplyTarget: params.sourceReplyTarget,
+                    targetReplyTarget: params.targetReplyTarget,
+                    relatedTaskRef: params.payload.relatedTaskRef,
+                }),
+            });
+        }
+        const cancelResult = params.conversationManager.cancelConversationRun(params.sourceConversationId, params.sourceConversationRunId, { strictExpectedRunId: true });
+        if (!cancelResult.ok || !cancelResult.runId) {
+            return { cancelRequested: false };
+        }
+        params.db.prepare(`DELETE FROM conversation_prompt_queue
+       WHERE conversation_id = ?
+         AND record_as_user_message = 0`).run(params.sourceConversationId);
+        return {
+            cancelRequested: true,
+            cancelRunId: cancelResult.runId,
+        };
+    };
+    const persistSourceCancellation = (record, cancelOutcome) => (cancelOutcome.cancelRunId
+        ? markConversationHandoffSourceCancelled(params.db, {
+            handoffId: record.handoffId,
+            cancelRunId: cancelOutcome.cancelRunId,
+        }) ?? record
+        : record);
+    const handoffCapsuleText = buildConversationHandoffCapsuleText({
+        mode: params.mode,
+        targetReplyTarget: params.targetReplyTarget,
+        payload: params.payload,
+    });
+    if (!params.dispatch) {
+        const failed = createConversationHandoff(params.db, {
+            agentId: params.agentId,
+            sourceConversationId: params.sourceConversationId,
+            targetConversationId: params.targetConversationId,
+            targetReplyTarget: params.targetReplyTarget,
+            workflowKind,
+            sourceDisposition,
+            taskId: params.taskId ?? null,
+            taskNumber: params.taskNumber ?? null,
+            mode: params.mode,
+            status: 'failed',
+            payload: {
+                ...params.payload,
+                error: params.dispatchBuildErrorText ?? `Failed to build handoff dispatch for ${params.targetReplyTarget}`,
+            },
+        });
+        const cancelOutcome = await cancelSourceRun(failureSourceDisposition);
+        const finalRecord = persistSourceCancellation(failed, cancelOutcome);
+        safeInvokeLifecycleCallback('onFailed', () => {
+            params.onFailed?.({
+                record: finalRecord,
+                cancelRequested: cancelOutcome.cancelRequested,
+                ...(cancelOutcome.cancelRunId ? { cancelRunId: cancelOutcome.cancelRunId } : {}),
+                sourceConversationRunId: params.sourceConversationRunId,
+            });
+        });
+        return {
+            status: 'failed',
+            handoffId: failed.handoffId,
+            queued: false,
+            targetConversationId: params.targetConversationId,
+            targetReplyTarget: params.targetReplyTarget,
+            cancelRequested: cancelOutcome.cancelRequested,
+            ...(cancelOutcome.cancelRunId ? { cancelRunId: cancelOutcome.cancelRunId } : {}),
+            error: failed.payload.error ?? params.dispatchBuildErrorText ?? 'Failed to build handoff dispatch',
+        };
+    }
+    const beforeDispatchState = params.getLatestConversationDispatchState(params.targetConversationId);
+    const finalizeStarted = async (result) => {
+        const record = createConversationHandoff(params.db, {
+            agentId: params.agentId,
+            sourceConversationId: params.sourceConversationId,
+            targetConversationId: params.targetConversationId,
+            targetReplyTarget: params.targetReplyTarget,
+            workflowKind,
+            sourceDisposition,
+            taskId: params.taskId ?? null,
+            taskNumber: params.taskNumber ?? null,
+            mode: params.mode,
+            status: 'started',
+            payload: {
+                ...params.payload,
+                ...(result?.runId ? { targetRunId: result.runId } : {}),
+            },
+        });
+        persistHandoffTargetSurfaceCheckpointSeedIfUnset(params.db, targetSurface, params.dispatch?.targetSurfaceCheckpointSeedSeq);
+        const cancelOutcome = await cancelSourceRun(sourceDisposition, {
+            sendContinueThereNotice: true,
+        });
+        const finalRecord = persistSourceCancellation(record, cancelOutcome);
+        if (result?.queued) {
+            safeInvokeLifecycleCallback('onQueued', () => {
+                params.onQueued?.(params.targetConversationId);
+            });
+        }
+        safeInvokeLifecycleCallback('onStarted', () => {
+            params.onStarted?.({
+                record: finalRecord,
+                cancelRequested: cancelOutcome.cancelRequested,
+                ...(cancelOutcome.cancelRunId ? { cancelRunId: cancelOutcome.cancelRunId } : {}),
+                sourceConversationRunId: params.sourceConversationRunId,
+            });
+        });
+        return {
+            status: 'started',
+            handoffId: record.handoffId,
+            queued: result?.queued ?? false,
+            targetConversationId: params.targetConversationId,
+            targetReplyTarget: params.targetReplyTarget,
+            ...(result?.runId ? { targetRunId: result.runId } : {}),
+            cancelRequested: cancelOutcome.cancelRequested,
+            ...(cancelOutcome.cancelRunId ? { cancelRunId: cancelOutcome.cancelRunId } : {}),
+        };
+    };
+    const handoffCorrelationId = randomUUID();
+    const handoffCapsuleSection = createPromptContextSection('handoff_capsule', handoffCapsuleText);
+    const dispatchOptionsWithCapsule = {
+        ...params.dispatch.options,
+        activationContextText: combinePromptSections([handoffCapsuleText, params.dispatch.options.activationContextText]),
+        activationContextSections: handoffCapsuleSection
+            ? [handoffCapsuleSection, ...(params.dispatch.options.activationContextSections ?? [])]
+            : params.dispatch.options.activationContextSections,
+        resumeContextText: combinePromptSections([handoffCapsuleText, params.dispatch.options.resumeContextText]),
+        resumeContextSections: handoffCapsuleSection
+            ? [handoffCapsuleSection, ...(params.dispatch.options.resumeContextSections ?? [])]
+            : params.dispatch.options.resumeContextSections,
+        activationMetadata: withHandoffDispatchMetadata(params.dispatch.options.activationMetadata, {
+            correlationId: handoffCorrelationId,
+            sourceConversationId: params.sourceConversationId,
+            targetConversationId: params.targetConversationId,
+        }),
+    };
+    try {
+        const result = await params.conversationManager.submitPrompt(params.targetConversationId, params.dispatch.promptText, dispatchOptionsWithCapsule);
+        return await finalizeStarted(result);
+    }
+    catch (error) {
+        const afterDispatchState = params.getLatestConversationDispatchState(params.targetConversationId);
+        const matchedQueuedDispatch = afterDispatchState.queueId !== null
+            && afterDispatchState.queueId !== beforeDispatchState.queueId
+            && queuedPromptMatchesHandoffCorrelation(params.db, afterDispatchState.queueId, handoffCorrelationId);
+        const matchedActiveRun = afterDispatchState.runId !== null
+            && afterDispatchState.runId !== beforeDispatchState.runId
+            && activeRunMatchesHandoffCorrelation(params.db, afterDispatchState.runId, handoffCorrelationId);
+        if (matchedQueuedDispatch || matchedActiveRun) {
+            return await finalizeStarted({
+                queued: matchedQueuedDispatch,
+                ...(matchedActiveRun && afterDispatchState.runId ? { runId: afterDispatchState.runId } : {}),
+            });
+        }
+        const errorText = String(error?.message ?? error);
+        const failed = createConversationHandoff(params.db, {
+            agentId: params.agentId,
+            sourceConversationId: params.sourceConversationId,
+            targetConversationId: params.targetConversationId,
+            targetReplyTarget: params.targetReplyTarget,
+            workflowKind,
+            sourceDisposition,
+            taskId: params.taskId ?? null,
+            taskNumber: params.taskNumber ?? null,
+            mode: params.mode,
+            status: 'failed',
+            payload: {
+                ...params.payload,
+                error: errorText,
+            },
+        });
+        const cancelOutcome = await cancelSourceRun(failureSourceDisposition);
+        const finalRecord = persistSourceCancellation(failed, cancelOutcome);
+        safeInvokeLifecycleCallback('onFailed', () => {
+            params.onFailed?.({
+                record: finalRecord,
+                cancelRequested: cancelOutcome.cancelRequested,
+                ...(cancelOutcome.cancelRunId ? { cancelRunId: cancelOutcome.cancelRunId } : {}),
+                sourceConversationRunId: params.sourceConversationRunId,
+            });
+        });
+        return {
+            status: 'failed',
+            handoffId: failed.handoffId,
+            queued: false,
+            targetConversationId: params.targetConversationId,
+            targetReplyTarget: params.targetReplyTarget,
+            cancelRequested: cancelOutcome.cancelRequested,
+            ...(cancelOutcome.cancelRunId ? { cancelRunId: cancelOutcome.cancelRunId } : {}),
+            error: errorText,
+        };
+    }
+}
+export function getLatestConversationDispatchState(db, conversationId) {
+    const queuedPrompt = db.prepare(`SELECT queue_id as queueId
+     FROM conversation_prompt_queue
+     WHERE conversation_id = ?
+     ORDER BY queue_id DESC
+     LIMIT 1`).get(conversationId);
+    const existingRun = db.prepare(`SELECT r.run_id as runId
+     FROM runs r
+     JOIN conversations c ON c.session_key = r.session_key
+     WHERE c.id = ?
+       AND r.ended_at IS NULL
+     ORDER BY r.started_at DESC
+     LIMIT 1`).get(conversationId);
+    return {
+        queueId: queuedPrompt?.queueId ?? null,
+        runId: existingRun?.runId ?? null,
+    };
+}
+function withHandoffDispatchMetadata(metadata, handoffDispatch) {
+    return {
+        ...(metadata ?? {}),
+        handoffDispatch,
+    };
+}
+function queuedPromptMatchesHandoffCorrelation(db, queueId, correlationId) {
+    const row = db.prepare(`SELECT activation_metadata_json as activationMetadataJson
+     FROM conversation_prompt_queue
+     WHERE queue_id = ?
+     LIMIT 1`).get(queueId);
+    return activationMetadataMatchesHandoffCorrelation(row?.activationMetadataJson, correlationId);
+}
+function activeRunMatchesHandoffCorrelation(db, runId, correlationId) {
+    const row = db.prepare(`SELECT r.ended_at as endedAt,
+            rdi.activation_metadata_json as activationMetadataJson
+     FROM runs r
+     LEFT JOIN run_debug_inputs rdi ON rdi.run_id = r.run_id
+     WHERE r.run_id = ?
+     LIMIT 1`).get(runId);
+    return row?.endedAt == null
+        && activationMetadataMatchesHandoffCorrelation(row?.activationMetadataJson, correlationId);
+}
+function activationMetadataMatchesHandoffCorrelation(rawMetadata, correlationId) {
+    if (!rawMetadata)
+        return false;
+    try {
+        const parsed = JSON.parse(rawMetadata);
+        return parsed?.handoffDispatch?.correlationId === correlationId;
+    }
+    catch {
+        return false;
+    }
+}
+function nextSyntheticRunEventSeq(db, runId) {
+    const row = db.prepare(`SELECT COALESCE(MAX(seq), 0) as maxSeq
+     FROM events
+     WHERE run_id = ?`).get(runId);
+    return Number(row?.maxSeq ?? 0) + 1;
+}
+function loadLatestChannelSeq(db, channelId) {
+    const row = db.prepare(`SELECT COALESCE(MAX(seq), 0) as maxSeq
+     FROM channel_messages
+     WHERE channel_id = ?`).get(channelId);
+    return Number(row?.maxSeq ?? 0);
+}
+export function buildSameAgentHandoffDispatchPlan(params) {
+    const conversation = params.conversationManager.getConversation(params.targetConversationId);
+    if (!conversation?.agentId)
+        return null;
+    const replyTarget = (resolveDefaultReplyTarget(params.db, conversation.id, params.humanUserName) ?? conversation.replyTarget ?? '').trim();
+    if (!replyTarget)
+        return null;
+    const channelId = conversation.threadKind === 'direct'
+        ? `dm:${conversation.agentId}`
+        : conversation.channelId;
+    if (!channelId)
+        return null;
+    const targetSurface = {
+        agentId: conversation.agentId,
+        channelId,
+        replyTarget,
+        threadRootId: conversation.threadRootId ?? null,
+    };
+    const targetSurfaceCheckpointSeedSeq = loadHandoffTargetSurfaceCheckpointSeedSeq(params.db, targetSurface);
+    if (conversation.threadKind === 'direct') {
+        const directEnvelopeOverrides = params.directEnvelopeOverrides ?? {};
+        const envelope = buildDirectSurfaceActivationEnvelope(params.db, {
+            agentId: conversation.agentId,
+            channelId,
+            replyTarget,
+            triggerSeq: params.triggerSeqOverride ?? (loadLatestChannelSeq(params.db, channelId) + 1),
+            threadRootId: conversation.threadRootId ?? undefined,
+            unreadCheckpointSeq: directEnvelopeOverrides.unreadCheckpointSeq ?? targetSurfaceCheckpointSeedSeq ?? undefined,
+            ...directEnvelopeOverrides,
+            strongSignalFlags: {
+                open_handoff: true,
+                explicit_handoff_target: true,
+                ...directEnvelopeOverrides.strongSignalFlags,
+            },
+        });
+        return {
+            promptText: params.promptText,
+            targetSurfaceCheckpointSeedSeq,
+            options: {
+                recordAsUserMessage: false,
+                activationContextText: envelope.activationContextText,
+                activationContextSections: envelope.activationContextSections,
+                resumeContextText: envelope.resumeContextText,
+                resumeContextSections: envelope.resumeContextSections,
+                replayOverlapRecentMessages: envelope.replayOverlapRecentMessages,
+                allowActiveSteer: false,
+                ...(params.suppressReplyContract === true ? { suppressReplyContract: true } : {}),
+                ...(params.activationMetadata ? { activationMetadata: params.activationMetadata } : {}),
+                ...(params.attachments?.length ? { attachments: params.attachments } : {}),
+                ...(params.attachmentIds?.length ? { attachmentIds: params.attachmentIds } : {}),
+            },
+        };
+    }
+    const channelEnvelopeOverrides = params.channelEnvelopeOverrides ?? {};
+    const channel = params.conversationManager.getChannel(conversation.channelId);
+    const envelope = buildChannelSurfaceActivationEnvelope(params.db, {
+        agentId: conversation.agentId,
+        channelId,
+        replyTarget,
+        triggerSeq: params.triggerSeqOverride ?? (loadLatestChannelSeq(params.db, channelId) + 1),
+        threadRootId: conversation.threadRootId ?? undefined,
+        channelName: channel?.name,
+        reason: 'channel_activity',
+        unreadCheckpointSeq: channelEnvelopeOverrides.unreadCheckpointSeq ?? targetSurfaceCheckpointSeedSeq ?? undefined,
+        ...channelEnvelopeOverrides,
+        strongSignalFlags: {
+            open_handoff: true,
+            explicit_handoff_target: true,
+            ...channelEnvelopeOverrides.strongSignalFlags,
+        },
+    });
+    return {
+        promptText: params.promptText,
+        targetSurfaceCheckpointSeedSeq,
+        options: {
+            recordAsUserMessage: false,
+            activationContextText: envelope.activationContextText,
+            activationContextSections: envelope.activationContextSections,
+            resumeContextText: envelope.resumeContextText,
+            resumeContextSections: envelope.resumeContextSections,
+            replayOverlapRecentMessages: envelope.replayOverlapRecentMessages,
+            allowActiveSteer: false,
+            ...(params.suppressReplyContract === true ? { suppressReplyContract: true } : {}),
+            ...(params.activationMetadata ? { activationMetadata: params.activationMetadata } : {}),
+            ...(params.attachments?.length ? { attachments: params.attachments } : {}),
+            ...(params.attachmentIds?.length ? { attachmentIds: params.attachmentIds } : {}),
+        },
+    };
+}
+export async function startConversationHandoff(params) {
+    const dispatch = buildSameAgentHandoffDispatchPlan({
+        db: params.db,
+        conversationManager: params.conversationManager,
+        humanUserName: params.humanUserName,
+        targetConversationId: params.targetConversationId,
+        promptText: buildConversationHandoffPrompt({
+            mode: params.mode,
+            targetReplyTarget: params.targetReplyTarget,
+            payload: params.payload,
+        }),
+    });
+    return performSameAgentHandoff({
+        agentId: params.agentId,
+        db: params.db,
+        conversationManager: params.conversationManager,
+        getLatestConversationDispatchState: (conversationId) => getLatestConversationDispatchState(params.db, conversationId),
+        sourceConversationId: params.sourceConversationId,
+        sourceConversationRunId: params.sourceConversationRunId,
+        sourceReplyTarget: params.sourceReplyTarget,
+        targetConversationId: params.targetConversationId,
+        targetReplyTarget: params.targetReplyTarget,
+        mode: params.mode,
+        payload: params.payload,
+        taskId: params.taskId ?? null,
+        taskNumber: params.taskNumber ?? null,
+        dispatch,
+        dispatchBuildErrorText: `Failed to build handoff dispatch for ${params.targetReplyTarget}`,
+        onQueued: (targetConversationId) => {
+            params.broadcastConversationStatus?.(targetConversationId, 'queued');
+        },
+        onStarted: ({ record, cancelRequested, cancelRunId, sourceConversationRunId }) => {
+            if (!cancelRequested || !cancelRunId || !sourceConversationRunId)
+                return;
+            params.db.prepare(`INSERT INTO events(run_id, seq, method, payload_json, created_at)
+         VALUES(?, ?, ?, ?, ?)`).run(sourceConversationRunId, nextSyntheticRunEventSeq(params.db, sourceConversationRunId), params.handoffEventMethod ?? 'platform/handoff', JSON.stringify({
+                kind: 'conversation_handoff',
+                handoffId: record.handoffId,
+                mode: params.mode,
+                sourceTarget: params.sourceReplyTarget,
+                targetReplyTarget: params.targetReplyTarget,
+                targetConversationId: params.targetConversationId,
+                cancelRunId,
+                status: 'started',
+            }), Date.now());
+        },
+    });
+}