@indexnetwork/protocol 6.12.0-rc.403.1 → 6.13.22-rc.405.1

package/dist/opportunity/application/opportunity.discover.js

@@ -0,0 +1,793 @@
+/**
+ * Run discovery from an ad-hoc query (e.g. chat "find me a mentor", "who needs a React developer").
+ *
+ * Invokes the opportunity graph with the query as sourceText. The HyDE graph's
+ * LensInferrer automatically infers search lenses from the query, replacing the
+ * old hardcoded strategy selection. Returns formatted candidates (enriched with
+ * profile name/bio) for chat display.
+ *
+ * Used by the discover_opportunities chat tool.
+ */
+import { discoveryQuestionsInputMode, discoveryQuestionsTimeoutMs } from "../../capabilities/questions.runtime.facade.js";
+import { gatherPresenterContext } from "./opportunity.presenter.js";
+import { MINIMAL_MAIN_TEXT_MAX_CHARS, getPrimaryActionLabel, SECONDARY_ACTION_LABEL } from "../domain/opportunity.labels.js";
+import { narratorRemarkFromReasoning } from "../domain/opportunity.presentation.js";
+import { safeFallbackSummary } from "../domain/opportunity.safe-presentation.js";
+import { protocolLogger, withCallLogging } from "../../shared/observability/protocol.logger.js";
+import { traceAgent, tracePhase } from "../../shared/observability/trace.js";
+import { requestContext } from "../../shared/observability/request-context.js";
+import { buildDiscoveryQuestionInput } from "../domain/discovery-question.helper.js";
+import { invokeWithAbortSignal } from "../../shared/agent/model-signal.js";
+import { summarizeDiscoveryNegotiations } from "./opportunity.discovery-negotiation-summary.js";
+import { finalizeDiscoveryContinuation } from './opportunity.discovery-continuation-finalization.js';
+const logger = protocolLogger("OpportunityDiscover");
+const discoverFromQueryLog = protocolLogger("OpportunityDiscover:runDiscoverFromQuery");
+const enrichLog = protocolLogger("OpportunityDiscover:enrichOpportunities");
+function combineWithDeadline(callerSignal, deadlineMs) {
+    const deadline = AbortSignal.timeout(deadlineMs);
+    if (!callerSignal)
+        return deadline;
+    return AbortSignal.any([callerSignal, deadline]);
+}
+/** Max chars for bio and matchReason in chat tool results to keep context manageable. */
+const MAX_FIELD_CHARS = 100;
+function truncateForChat(s, max = MAX_FIELD_CHARS) {
+    if (s == null || s === "")
+        return undefined;
+    const trimmed = s.trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return trimmed.slice(0, max) + "...";
+}
+/** Statuses for which an existing connection may be shown as a card; others (accepted, rejected, expired) are only mentioned in text. */
+const EXISTING_CONNECTION_CARD_STATUSES = ['draft', 'latent', 'pending'];
+/**
+ * Enrich raw opportunities with profile data, presentation (LLM or minimal),
+ * and narrator chips. Shared by both `runDiscoverFromQuery` and `continueDiscovery`
+ * to avoid duplicating the profile-lookup / presenter / card-formatting logic.
+ *
+ * @param input - Enrichment context (opportunities, database, viewer, presentation options).
+ * @returns Formatted discovery candidates ready for chat or home card display.
+ */
+async function enrichOpportunities(input) {
+    const { opportunities, database, userId, chatSessionId, minimalForChat, presenter, useHomeCardFormat, debugSteps, existingOpportunityIds, preserveLifecycleStatus, targetUserId, } = input;
+    const baseEnrichedRaw = await Promise.all(opportunities.map(async (opp) => {
+        const viewerIsIntroducer = opp.actors.some((a) => a.role === 'introducer' && a.userId === userId);
+        // When the viewer is the introducer, the "candidate" for the card is the agent
+        // (the discovered person), not the patient (the intro target / onBehalfOfUserId).
+        // For non-introducer views, pick the first non-viewer, non-introducer actor.
+        const nonViewerNonIntroducerActors = opp.actors.filter((a) => a.userId !== userId && a.role !== 'introducer');
+        const candidateActor = viewerIsIntroducer
+            ? (nonViewerNonIntroducerActors.find((a) => a.role === 'agent') ?? nonViewerNonIntroducerActors[0])
+            : nonViewerNonIntroducerActors[0];
+        const candidateUserId = candidateActor?.userId ?? "";
+        const viewerActor = opp.actors.find((a) => a.userId === userId);
+        const [profile, candidateUser] = candidateUserId
+            ? await Promise.all([database.getProfile(candidateUserId), database.getUser(candidateUserId)])
+            : [null, null];
+        // Skip soft-deleted users (deletedAt is set)
+        if (candidateUser && 'deletedAt' in candidateUser && candidateUser.deletedAt)
+            return null;
+        const isDirectTarget = targetUserId && candidateUserId === targetUserId;
+        if (!isDirectTarget && !candidateUser?.isGhost && !profile)
+            return null;
+        const confidence = typeof opp.interpretation?.confidence === "number"
+            ? opp.interpretation.confidence
+            : parseFloat(String(opp.interpretation?.confidence ?? 0)) || 0;
+        return {
+            opportunity: opp,
+            candidateUserId,
+            viewerRole: viewerActor?.role ?? "party",
+            viewerApproved: viewerActor?.approved === true,
+            viewerActedAt: viewerActor?.actedAt ?? null,
+            candidateUser,
+            profile,
+            confidence,
+        };
+    }));
+    const baseEnriched = baseEnrichedRaw.filter((item) => item !== null);
+    debugSteps.push({
+        step: "enrich_profiles",
+        detail: `${baseEnriched.length} profile(s)`,
+    });
+    // Batch-fetch user records (candidates, introducers, and other party actors) for name/avatar fallback.
+    const allActorUserIds = new Set();
+    for (const item of baseEnriched) {
+        for (const actor of item.opportunity.actors) {
+            if (actor.userId && actor.userId !== userId) {
+                allActorUserIds.add(actor.userId);
+            }
+        }
+    }
+    const candidateUserIds = [...allActorUserIds];
+    const [viewerUser, ...userResults] = await Promise.all([
+        database.getUser(userId),
+        ...candidateUserIds.map((id) => database.getUser(id)),
+    ]);
+    const avatarByUserId = new Map();
+    const nameByUserId = new Map();
+    const isGhostByUserId = new Map();
+    candidateUserIds.forEach((id, i) => {
+        const user = userResults[i] ?? null;
+        avatarByUserId.set(id, user?.avatar ?? null);
+        nameByUserId.set(id, user?.name ?? null);
+        isGhostByUserId.set(id, user?.isGhost ?? false);
+    });
+    const viewerName = viewerUser?.name ?? undefined;
+    // Retry name resolution for candidates whose name is still missing.
+    // The profile or user record may not have been ready on the first fetch
+    // (e.g. profile generation still in flight). One retry covers transient gaps.
+    const missingNameIds = baseEnriched
+        .map((item) => item.candidateUserId)
+        .filter((id) => id && !nameByUserId.get(id) && !baseEnriched.find((b) => b.candidateUserId === id && b.profile?.identity?.name));
+    if (missingNameIds.length > 0) {
+        const retried = await Promise.all(missingNameIds.map(async (id) => {
+            const [profile, user] = await Promise.all([
+                database.getProfile(id),
+                database.getUser(id),
+            ]);
+            return { id, profile, user };
+        }));
+        for (const r of retried) {
+            const name = r.profile?.identity?.name ?? r.user?.name ?? null;
+            if (name)
+                nameByUserId.set(r.id, name);
+            // Also update the baseEnriched profile so counterpartName picks it up
+            if (r.profile) {
+                const item = baseEnriched.find((b) => b.candidateUserId === r.id);
+                if (item && !item.profile)
+                    item.profile = r.profile;
+            }
+            if (r.user?.avatar && !avatarByUserId.get(r.id)) {
+                avatarByUserId.set(r.id, r.user.avatar);
+            }
+        }
+        enrichLog.verbose("Retried name lookup for candidates with missing names", {
+            attempted: missingNameIds.length,
+            resolved: retried.filter((r) => r.profile?.identity?.name ?? r.user?.name).length,
+        });
+    }
+    let presentations;
+    let homeCardPresentations;
+    let presenterContexts;
+    if (minimalForChat && baseEnriched.length > 0) {
+        // Minimal path: no LLM, viewer-centric card text (introduce counterpart to viewer)
+        const counterpartName = (n) => n.profile?.identity?.name ?? nameByUserId.get(n.candidateUserId) ?? "";
+        homeCardPresentations = baseEnriched.map((item) => {
+            const name = counterpartName(item)?.trim();
+            const reasoning = item.opportunity.interpretation?.reasoning ?? "";
+            const introducerName = item.opportunity.detection?.createdByName ?? undefined;
+            const viewerIsIntroducer = item.opportunity.actors.some((a) => a.role === "introducer" && a.userId === userId);
+            // For introducer view, find the second party (target user) name
+            let secondPartyName;
+            if (viewerIsIntroducer) {
+                const otherPartyActors = item.opportunity.actors.filter((a) => a.role !== "introducer" && a.userId !== item.candidateUserId);
+                if (otherPartyActors.length > 0) {
+                    const otherUserId = otherPartyActors[0].userId;
+                    secondPartyName = nameByUserId.get(otherUserId) ?? undefined;
+                }
+            }
+            // Shared sanitization standard — see opportunity.safe-presentation.ts.
+            const personalizedSummary = safeFallbackSummary(reasoning, {
+                counterpartName: name,
+                viewerName,
+                introducerName,
+                maxChars: MINIMAL_MAIN_TEXT_MAX_CHARS,
+                emptyText: "A suggested connection.",
+            });
+            return {
+                headline: viewerIsIntroducer && secondPartyName
+                    ? `${name} → ${secondPartyName}`
+                    : (name ? `Connection with ${name}` : "Suggested connection"),
+                personalizedSummary,
+                digestSummary: name
+                    ? `You might like meeting ${name} based on your current interests.`
+                    : "This connection may be relevant to your current interests.",
+                suggestedAction: "Start a conversation to connect.",
+                narratorRemark: narratorRemarkFromReasoning(reasoning, name, viewerName),
+                primaryActionLabel: getPrimaryActionLabel(viewerIsIntroducer ? "introducer" : "party"),
+                secondaryActionLabel: SECONDARY_ACTION_LABEL,
+                mutualIntentsLabel: "Suggested connection",
+                greeting: "",
+            };
+        });
+        presenterContexts = baseEnriched.map((item) => ({
+            introducerName: item.opportunity.detection.createdByName ?? undefined,
+        }));
+    }
+    else if (presenter && baseEnriched.length > 0) {
+        try {
+            presenterContexts = await Promise.all(baseEnriched.map(({ opportunity }) => gatherPresenterContext(database, opportunity, userId)));
+            if (useHomeCardFormat) {
+                // Use full home card format with action labels, narrator remark, etc.
+                const fullContexts = presenterContexts;
+                const homeCardInputs = fullContexts.map((ctx, idx) => ({
+                    ...ctx,
+                    mutualIntentCount: undefined,
+                    opportunityStatus: baseEnriched[idx].opportunity.status,
+                }));
+                const llmResults = await presenter.presentHomeCardBatch(homeCardInputs, { concurrency: 5 });
+                // Append hardcoded button labels to LLM results
+                homeCardPresentations = llmResults.map((llm, idx) => ({
+                    ...llm,
+                    primaryActionLabel: getPrimaryActionLabel(baseEnriched[idx].viewerRole),
+                    secondaryActionLabel: SECONDARY_ACTION_LABEL,
+                }));
+            }
+            else {
+                // Use basic presentation format
+                presentations = await presenter.presentBatch(presenterContexts, {
+                    concurrency: 5,
+                });
+            }
+        }
+        catch (error) {
+            logger.warn("Presenter enrichment failed during opportunity discovery; returning base results without presentations", {
+                userId,
+                opportunitiesCount: baseEnriched.length,
+                useHomeCardFormat,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            presentations = undefined;
+            homeCardPresentations = undefined;
+        }
+    }
+    const enriched = baseEnriched.map((item, idx) => {
+        const homeCard = homeCardPresentations?.[idx];
+        const ctx = presenterContexts?.[idx];
+        // Build narrator chip for home card format
+        let narratorChip;
+        if (homeCard) {
+            const viewerIsIntroducer = item.opportunity.actors.some((a) => a.role === "introducer" && a.userId === userId);
+            if (viewerIsIntroducer) {
+                narratorChip = {
+                    name: "You",
+                    text: homeCard.narratorRemark,
+                    userId: userId,
+                };
+            }
+            else {
+                const introducerActor = item.opportunity.actors.find((a) => a.role === "introducer" && a.userId !== userId);
+                if (introducerActor) {
+                    const introducerName = ctx?.introducerName ??
+                        nameByUserId.get(introducerActor.userId) ??
+                        "Someone";
+                    narratorChip = {
+                        name: introducerName,
+                        text: homeCard.narratorRemark,
+                        userId: introducerActor.userId,
+                        avatar: avatarByUserId.get(introducerActor.userId) ?? null,
+                    };
+                }
+                else {
+                    narratorChip = {
+                        name: "Index",
+                        text: homeCard.narratorRemark,
+                    };
+                }
+            }
+        }
+        const isGhost = isGhostByUserId.get(item.candidateUserId) ?? false;
+        // Build secondParty for introducer view (the other non-introducer party)
+        let secondParty;
+        const viewerIsIntroducerForCard = item.opportunity.actors.some((a) => a.role === "introducer" && a.userId === userId);
+        if (viewerIsIntroducerForCard) {
+            const otherPartyActor = item.opportunity.actors.find((a) => a.role !== "introducer" && a.userId !== item.candidateUserId);
+            if (otherPartyActor) {
+                const otherName = nameByUserId.get(otherPartyActor.userId) ?? undefined;
+                if (otherName) {
+                    secondParty = {
+                        name: otherName,
+                        avatar: avatarByUserId.get(otherPartyActor.userId) ?? null,
+                        userId: otherPartyActor.userId,
+                    };
+                }
+            }
+        }
+        return {
+            opportunityId: item.opportunity.id,
+            userId: item.candidateUserId,
+            name: item.profile?.identity?.name ?? nameByUserId.get(item.candidateUserId) ?? undefined,
+            avatar: avatarByUserId.get(item.candidateUserId) ?? null,
+            bio: truncateForChat(item.profile?.identity?.bio),
+            matchReason: safeFallbackSummary(item.opportunity.interpretation?.reasoning, {
+                counterpartName: item.profile?.identity?.name ?? nameByUserId.get(item.candidateUserId) ?? undefined,
+                viewerName,
+                maxChars: MAX_FIELD_CHARS,
+                emptyText: "A suggested connection.",
+            }),
+            score: item.confidence,
+            status: !preserveLifecycleStatus && chatSessionId && !existingOpportunityIds?.has(item.opportunity.id)
+                ? "draft"
+                : item.opportunity.status,
+            viewerRole: item.viewerRole,
+            viewerApproved: item.viewerApproved,
+            viewerActedAt: item.viewerActedAt,
+            candidateUser: item.candidateUser,
+            isGhost,
+            ...(presentations?.[idx] && { presentation: presentations[idx] }),
+            ...(homeCard && {
+                homeCardPresentation: homeCard,
+            }),
+            ...(narratorChip && { narratorChip }),
+            ...(secondParty && { secondParty }),
+        };
+    });
+    debugSteps.push({
+        step: "format_cards",
+        detail: `${enriched.length} card(s)`,
+    });
+    return enriched;
+}
+/**
+ * Run discovery from an ad-hoc query (e.g. "find me a mentor", "who needs a React developer").
+ * The HyDE graph's LensInferrer automatically infers search lenses from the query.
+ * Invokes the opportunity graph and returns formatted candidates suitable for chat display.
+ */
+export async function runDiscoverFromQuery(input) {
+    const { opportunityGraph, database, userId, query, indexScope, limit = 5, triggerIntentId, targetUserId, onBehalfOfUserId, chatSessionId, trigger, negotiateTimeoutMs, } = input;
+    if (indexScope.length === 0) {
+        return {
+            found: false,
+            count: 0,
+            message: "You need to join at least one network (community) to discover opportunities. Use read_networks to see available networks, or create one.",
+        };
+    }
+    const debugSteps = [];
+    // When query is empty, the opportunity graph uses the user's intents in scope (indexedIntents[0].payload)
+    // Lens inference is handled automatically by the HyDE graph's LensInferrer
+    const queryOrEmpty = query?.trim() ?? "";
+    // Orchestrator discovery defers the initial status to the graph's
+    // trigger-aware `resolveInitialStatus`, which opens at 'negotiating' so
+    // the accepted-draft streaming flow can run. Ambient chat discovery still
+    // wants the legacy 'draft' status so the chat-only lifecycle holds; other
+    // ambient callers keep 'latent'.
+    const isOrchestrator = trigger === 'orchestrator';
+    const options = {
+        limit,
+        ...(!isOrchestrator && { initialStatus: chatSessionId ? "draft" : "latent" }),
+        ...(chatSessionId ? { conversationId: chatSessionId } : {}),
+        ...(negotiateTimeoutMs !== undefined && { negotiateTimeoutMs }),
+    };
+    return withCallLogging(logger, "runDiscoverFromQuery", {
+        userId,
+        queryPreview: queryOrEmpty
+            ? queryOrEmpty.substring(0, 50)
+            : "(using user intents in scope)",
+        indexScopeCount: indexScope.length,
+        limit,
+    }, async () => {
+        const result = await invokeWithAbortSignal(opportunityGraph, {
+            userId,
+            searchQuery: queryOrEmpty || undefined,
+            // A single index resolves to the strict networkId override (membership-
+            // validated in the scope node). Multiple indexes (e.g. a network-scoped
+            // agent's bound network + personal network) pass through as indexScope so
+            // the graph stays bounded instead of falling back to all networks.
+            networkId: indexScope.length === 1 ? indexScope[0] : undefined,
+            ...(indexScope.length > 1 ? { indexScope } : {}),
+            triggerIntentId,
+            targetUserId,
+            onBehalfOfUserId,
+            options,
+            ...(trigger && { trigger }),
+        });
+        // Extract trace from graph and append to debugSteps
+        const graphTrace = Array.isArray(result.trace) ? result.trace : [];
+        for (const t of graphTrace) {
+            debugSteps.push({
+                step: t.node,
+                detail: t.detail,
+                ...(t.data ? { data: t.data } : {}),
+            });
+        }
+        // Bail early if the graph returned an error
+        if (result.error) {
+            logger.warn("runDiscoverFromQuery graph returned error", { error: result.error });
+            return {
+                found: false,
+                count: 0,
+                message: "Failed to find opportunities. Please try again.",
+                debugSteps,
+            };
+        }
+        // Cache remaining candidates for pagination
+        let pagination;
+        const remainingCandidates = result.remainingCandidates || [];
+        if (remainingCandidates.length > 0 && input.cache) {
+            try {
+                const discoveryId = crypto.randomUUID();
+                const cacheKey = `discovery:${userId}:${discoveryId}`;
+                await input.cache.set(cacheKey, {
+                    candidates: remainingCandidates,
+                    userId,
+                    onBehalfOfUserId,
+                    query: queryOrEmpty,
+                    indexScope,
+                    options,
+                    ...(trigger && { trigger }),
+                }, { ttl: 1800 }); // 30 minutes
+                pagination = {
+                    discoveryId,
+                    evaluated: (result.candidates?.length ?? 0) - remainingCandidates.length,
+                    remaining: remainingCandidates.length,
+                };
+            }
+            catch (cacheErr) {
+                logger.warn("Failed to cache discovery pagination", {
+                    userId,
+                    error: cacheErr instanceof Error ? cacheErr.message : String(cacheErr),
+                });
+            }
+        }
+        // Refine phase: a sibling of the opportunity graph in the trace tree.
+        // Holds the three post-discovery summarization steps. Each step is its
+        // own traced agent so it appears as a leaf in the trace UI.
+        //
+        // Negotiation summary: compress each raw negotiation into a fixed-size
+        // structured digest so the question generator's prompt stays small
+        // (a 10-candidate turn used to balloon past 60 KB and stall upstream).
+        // Decision questions: generate up to 3 clarifying questions from the
+        // digests + chat context.
+        const { questionPayload } = await tracePhase("Refine", async () => {
+            const negotiations = result.discoveryNegotiations ?? [];
+            const negotiationDigests = input.enableQuestions && trigger === 'orchestrator' && negotiations.length > 0
+                ? await summarizeDiscoveryNegotiations({
+                    negotiations,
+                    summarizer: input.negotiationSummary,
+                    callerSignal: requestContext.getStore()?.abortSignal,
+                })
+                : [];
+            const questionPayload = await maybeBuildQuestions({
+                trigger,
+                enableQuestions: input.enableQuestions ?? false,
+                chatSummary: input.chatSummary,
+                questionGenerator: input.questionGenerator,
+                chatSessionId,
+                graphResult: result,
+                negotiationDigests,
+                query: queryOrEmpty,
+                questionerEnqueue: input.questionerEnqueue,
+                userId: input.userId,
+                scopeType: input.scopeType,
+                scopeId: input.scopeId,
+                triggerIntentId,
+                userContext: input.userId
+                    ? ((await input.database.getUserContext(input.userId, null))?.text ?? '')
+                    : '',
+            });
+            return { negotiationDigests, questionPayload };
+        });
+        if (result.createIntentSuggested && result.suggestedIntentDescription) {
+            if (chatSessionId) {
+                return {
+                    found: false,
+                    count: 0,
+                    message: "No matching opportunities found. Try a different query.",
+                    pagination,
+                    ...(questionPayload.questions !== undefined ? { questions: questionPayload.questions } : {}),
+                    ...(questionPayload.debug !== undefined ? { discoveryQuestionsDebug: questionPayload.debug } : {}),
+                };
+            }
+            return {
+                found: false,
+                count: 0,
+                createIntentSuggested: true,
+                suggestedIntentDescription: result.suggestedIntentDescription,
+                message: "No matching opportunities; add an intent with the suggested description to improve discovery.",
+                debugSteps,
+                pagination,
+                ...(questionPayload.questions !== undefined ? { questions: questionPayload.questions } : {}),
+                ...(questionPayload.debug !== undefined ? { discoveryQuestionsDebug: questionPayload.debug } : {}),
+            };
+        }
+        let opportunities = Array.isArray(result.opportunities)
+            ? result.opportunities
+            : [];
+        let existingOpportunityIds;
+        const rawExistingBetweenActors = Array.isArray(result.existingBetweenActors)
+            ? result.existingBetweenActors
+            : [];
+        // Orchestrator trigger populates this; ambient returns []. Kept as a
+        // loosely-typed pass-through because DiscoverResult is consumed by
+        // callers (chat tool, tests) that already model the narrower shape.
+        const alreadyAcceptedPairs = Array.isArray(result
+            .dedupAlreadyAccepted)
+            ? result
+                .dedupAlreadyAccepted
+            : [];
+        // Enrich existing-between-actors with names so the tool can say "You already have a connection with X (pending)."
+        const existingConnections = await Promise.all(rawExistingBetweenActors.map(async (item) => {
+            const user = await database.getUser(item.candidateUserId);
+            return {
+                userId: item.candidateUserId,
+                name: user?.name ?? "Someone",
+                ...(item.existingStatus ? { status: item.existingStatus } : {}),
+                ...(item.existingOpportunityId ? { opportunityId: item.existingOpportunityId } : {}),
+            };
+        }));
+        if (existingConnections.length > 0) {
+            discoverFromQueryLog.verbose("Skipped duplicates; existing connections", {
+                count: existingConnections.length,
+                userIds: existingConnections.map((c) => c.userId),
+            });
+        }
+        // Only expose existing connections as cards when status is in EXISTING_CONNECTION_CARD_STATUSES (draft, latent, pending); others are mention-only.
+        const existingConnectionsForCards = existingConnections.filter((c) => c.status != null && EXISTING_CONNECTION_CARD_STATUSES.includes(c.status));
+        // Fetch full opportunity data for existing connections that should be shown as cards
+        // and merge them with the newly created opportunities
+        if (existingConnectionsForCards.length > 0) {
+            const existingOpps = await Promise.all(existingConnectionsForCards
+                .filter((c) => c.opportunityId)
+                .map((c) => database.getOpportunity(c.opportunityId)));
+            const validExistingOpps = existingOpps.filter((o) => o != null);
+            if (validExistingOpps.length > 0) {
+                discoverFromQueryLog.verbose("Including existing opportunities as cards", {
+                    count: validExistingOpps.length,
+                    ids: validExistingOpps.map((o) => o.id),
+                });
+                existingOpportunityIds = new Set(validExistingOpps.map((o) => o.id));
+                opportunities = [...opportunities, ...validExistingOpps];
+            }
+        }
+        // Chat discovery: when we have chatSessionId we just invoked the graph; all result.opportunities
+        // were created in this call and belong to this session. Do not filter by status: the enricher
+        // may set status to pending/latent when merging with related opportunities, so filtering to
+        // "draft" would incorrectly drop them.
+        if (chatSessionId && (result.opportunities?.length ?? 0) > 0) {
+            discoverFromQueryLog.verbose("Chat session opportunities from graph", {
+                count: opportunities.length,
+                statuses: opportunities.map((o) => o.status),
+            });
+        }
+        debugSteps.push({
+            step: "opportunity_graph",
+            detail: `${opportunities.length} opportunity(ies)${existingConnections.length > 0 ? `, ${existingConnections.length} existing` : ""}`,
+        });
+        if (opportunities.length === 0) {
+            if (existingConnections.length > 0) {
+                return {
+                    found: true,
+                    count: 0,
+                    message: "No new opportunities created; you already have a connection with: " +
+                        existingConnections.map((c) => `${c.name}${c.status ? ` (${c.status})` : ""}`).join(", ") +
+                        ". View on your home page.",
+                    existingConnections: existingConnectionsForCards,
+                    existingConnectionsForMention: existingConnections,
+                    ...(alreadyAcceptedPairs.length > 0 && { alreadyAcceptedPairs }),
+                    debugSteps,
+                    pagination,
+                    ...(questionPayload.questions !== undefined ? { questions: questionPayload.questions } : {}),
+                    ...(questionPayload.debug !== undefined ? { discoveryQuestionsDebug: questionPayload.debug } : {}),
+                };
+            }
+            return {
+                found: false,
+                count: 0,
+                message: "No matching opportunities found. Try a different query or create intents to improve matching.",
+                ...(alreadyAcceptedPairs.length > 0 && { alreadyAcceptedPairs }),
+                debugSteps,
+                pagination,
+                ...(questionPayload.questions !== undefined ? { questions: questionPayload.questions } : {}),
+                ...(questionPayload.debug !== undefined ? { discoveryQuestionsDebug: questionPayload.debug } : {}),
+            };
+        }
+        const enriched = await enrichOpportunities({
+            opportunities,
+            database,
+            userId,
+            chatSessionId,
+            minimalForChat: input.minimalForChat,
+            presenter: input.presenter,
+            useHomeCardFormat: input.useHomeCardFormat,
+            debugSteps,
+            existingOpportunityIds,
+            targetUserId,
+        });
+        return {
+            found: true,
+            count: enriched.length,
+            opportunities: enriched,
+            ...(existingConnectionsForCards.length > 0 ? { existingConnections: existingConnectionsForCards } : {}),
+            ...(existingConnections.length > 0 ? { existingConnectionsForMention: existingConnections } : {}),
+            ...(alreadyAcceptedPairs.length > 0 ? { alreadyAcceptedPairs } : {}),
+            debugSteps,
+            pagination,
+            ...(questionPayload.questions !== undefined ? { questions: questionPayload.questions } : {}),
+            ...(questionPayload.debug !== undefined ? { discoveryQuestionsDebug: questionPayload.debug } : {}),
+        };
+    }, { context: { userId }, logOutput: false }).catch(() => {
+        return {
+            found: false,
+            count: 0,
+            message: "Failed to find opportunities. Please try again.",
+        };
+    });
+}
+async function maybeBuildQuestions(args) {
+    if (!args.enableQuestions)
+        return {};
+    if (args.trigger !== 'orchestrator')
+        return {};
+    // Hardcoded — `insights` mode is planned for a later slice. Warn if the env
+    // var is set so operators aren't surprised when reporting still says
+    // "transcripts".
+    if (discoveryQuestionsInputMode() === "insights") {
+        logger.warn("QUESTIONER_DISCOVERY_INPUT_MODE=insights is not yet implemented; falling back to transcripts");
+    }
+    const inputMode = "transcripts";
+    let chatContext;
+    if (args.chatSummary && args.chatSessionId) {
+        const sessionId = args.chatSessionId;
+        const summary = args.chatSummary;
+        chatContext = await traceAgent("Chat summary", async () => {
+            try {
+                return (await summary.getDigest(sessionId)) ?? undefined;
+            }
+            catch (err) {
+                logger.warn("chatSummary.getDigest threw — proceeding without digest", {
+                    sessionId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return undefined;
+            }
+        }, (digest) => (digest ? "loaded" : "empty"));
+    }
+    // ── Async enqueue path ──────────────────────────────────────────────────
+    // When questionerEnqueue is provided, dispatch question generation
+    // asynchronously to the background QuestionerQueue. This replaces the
+    // inline generator path. Questions will be persisted to DB by the queue
+    // worker and served via GET /api/questions.
+    if (args.questionerEnqueue && args.userId) {
+        const summary = args.graphResult.discoverySummary ?? {
+            totalCandidates: 0,
+            opportunitiesFound: 0,
+            noOpportunityCount: 0,
+            timeoutCount: 0,
+            roleDistribution: {},
+        };
+        const enqueueInput = buildDiscoveryQuestionInput({
+            query: args.query,
+            userContext: args.userContext ?? '',
+            negotiationDigests: args.negotiationDigests,
+            summary,
+            chatContext,
+            now: new Date().toISOString(),
+        });
+        try {
+            await args.questionerEnqueue({
+                mode: 'discovery',
+                userId: args.userId,
+                sourceType: 'discovery',
+                sourceId: args.chatSessionId ?? crypto.randomUUID(),
+                context: enqueueInput,
+                ...(args.scopeType && args.scopeId ? { scopeType: args.scopeType, scopeId: args.scopeId } : {}),
+                ...(args.triggerIntentId ? { triggeredByIntentId: args.triggerIntentId } : {}),
+                conversationId: args.chatSessionId,
+            });
+            logger.info("Question generation enqueued to QuestionerQueue", {
+                userId: args.userId,
+                trigger: args.trigger,
+            });
+        }
+        catch (err) {
+            logger.warn("Failed to enqueue question generation", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return {};
+    }
+    // ── Inline generator path (backward compat) ────────────────────────────
+    if (!args.questionGenerator)
+        return {};
+    const negotiationDigests = args.negotiationDigests;
+    const summary = args.graphResult.discoverySummary ?? {
+        totalCandidates: 0,
+        opportunitiesFound: 0,
+        noOpportunityCount: 0,
+        timeoutCount: 0,
+        roleDistribution: {},
+    };
+    const input = buildDiscoveryQuestionInput({
+        query: args.query,
+        userContext: args.userContext ?? '',
+        negotiationDigests,
+        summary,
+        chatContext,
+        now: new Date().toISOString(),
+    });
+    const questionGenerator = args.questionGenerator;
+    const generatorStart = Date.now();
+    const questionsTimeoutMs = discoveryQuestionsTimeoutMs();
+    const questionsSignal = combineWithDeadline(requestContext.getStore()?.abortSignal, questionsTimeoutMs);
+    const genResult = await traceAgent("Decision questions", async () => {
+        try {
+            return await questionGenerator.generate(input, { signal: questionsSignal });
+        }
+        catch (err) {
+            logger.warn("questionGenerator.generate threw — suppressing questions", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    }, (r) => {
+        const count = r?.questions?.length ?? 0;
+        return `${count} question${count === 1 ? "" : "s"}`;
+    });
+    const durationMs = Date.now() - generatorStart;
+    const finalCount = genResult?.questions?.length ?? 0;
+    const strategies = genResult?.strategies ?? [];
+    return {
+        ...(genResult && genResult.questions.length > 0 ? { questions: genResult.questions } : {}),
+        debug: {
+            inputMode,
+            finalCount,
+            strategies,
+            durationMs,
+        },
+    };
+}
+/**
+ * Continue a paginated discovery by evaluating the next batch of cached candidates.
+ * Loads candidates from Redis, invokes the opportunity graph in continue_discovery mode,
+ * then enriches and returns the results with updated pagination metadata.
+ *
+ * @param input - Continuation context (graph, database, cache, discoveryId, etc.).
+ * @returns Discovery result with enriched opportunities and pagination state.
+ */
+export async function continueDiscovery(input) {
+    const { opportunityGraph, database, cache, userId, discoveryId, expectedIndexId, limit = 20, chatSessionId, } = input;
+    const cacheKey = `discovery:${userId}:${discoveryId}`;
+    const cached = await cache.get(cacheKey);
+    if (!cached) {
+        return {
+            found: false,
+            count: 0,
+            message: "Discovery session expired or not found. Please start a new search.",
+        };
+    }
+    // Validate that the cached session's scope matches the current chat context
+    if (expectedIndexId && !cached.indexScope.includes(expectedIndexId)) {
+        return {
+            found: false,
+            count: 0,
+            message: "Discovery session was created in a different context. Please start a new search.",
+        };
+    }
+    const result = await invokeWithAbortSignal(opportunityGraph, {
+        userId,
+        searchQuery: cached.query || undefined,
+        candidates: cached.candidates,
+        operationMode: 'continue_discovery',
+        onBehalfOfUserId: cached.onBehalfOfUserId,
+        // Carry the original trigger so page 2+ stays on the same flow as page
+        // 1 (orchestrator negotiations with 60s park window + accepted-pair
+        // dedup, or ambient with 5-min park window).
+        ...(cached.trigger && { trigger: cached.trigger }),
+        options: {
+            ...cached.options,
+            limit,
+            ...(chatSessionId ? { conversationId: chatSessionId } : {}),
+        },
+    });
+    return finalizeDiscoveryContinuation({
+        result,
+        cache,
+        cacheKey,
+        cached,
+        userId,
+        discoveryId,
+        database,
+        enrich: (opportunities, debugSteps) => enrichOpportunities({
+            opportunities,
+            database,
+            userId,
+            chatSessionId,
+            minimalForChat: input.minimalForChat,
+            presenter: input.presenter,
+            useHomeCardFormat: input.useHomeCardFormat,
+            debugSteps,
+            preserveLifecycleStatus: true,
+        }),
+    });
+}