@indexnetwork/protocol 6.12.1-rc.404.1 → 6.14.0-rc.406.1

package/dist/opportunity/application/opportunity.introducer.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Introducer Discovery: proactive discovery of connector-flow opportunities
+ * between a user's contacts.
+ *
+ * Selects top-N contacts from the user's personal network and runs scoped
+ * HyDE discovery for each, creating latent introducer opportunities that
+ * the user (as introducer) must approve before parties see them.
+ */
+/** Maximum contacts to evaluate per maintenance cycle. */
+export declare const MAX_CONTACTS_PER_CYCLE = 5;
+/** Maximum candidate opportunities per contact. */
+export declare const MAX_CANDIDATES_PER_CONTACT = 3;
+/** Detection source value for introducer-discovered opportunities. */
+export declare const INTRODUCER_DISCOVERY_SOURCE: "introducer_discovery";
+/** A contact with their active intents, used for introducer discovery selection. */
+export interface ContactWithIntents {
+    userId: string;
+    /** Most recent intent updatedAt timestamp (ISO string or null). */
+    latestIntentAt: string | null;
+    /** Number of active intents this contact has. */
+    intentCount: number;
+}
+/** Database methods needed for introducer discovery contact selection. */
+export interface IntroducerDiscoveryDatabase {
+    /** Get the user's personal network ID. */
+    getPersonalIndexId(userId: string): Promise<string | null>;
+    /** Get contacts from a personal network with their intent freshness data. */
+    getContactsWithIntentFreshness(personalIndexId: string, ownerId: string, limit: number): Promise<ContactWithIntents[]>;
+}
+/** Queue interface for enqueuing introducer discovery jobs. */
+export interface IntroducerDiscoveryQueue {
+    addJob(data: {
+        intentId: string;
+        userId: string;
+        indexIds?: string[];
+        contactUserId?: string;
+    }, options?: {
+        priority?: number;
+        jobId?: string;
+    }): Promise<unknown>;
+}
+/** Result of a single introducer discovery cycle. */
+export interface IntroducerDiscoveryResult {
+    contactsEvaluated: number;
+    jobsEnqueued: number;
+    skippedReason?: string;
+}
+/**
+ * Select top-N contacts for introducer discovery, sorted by intent freshness.
+ * Contacts with no active intents are excluded.
+ *
+ * @param database - Database adapter with contact/intent queries
+ * @param userId - The introducer user
+ * @param limit - Max contacts to return (default MAX_CONTACTS_PER_CYCLE)
+ * @returns Sorted contacts with intent data
+ */
+export declare function selectContactsForDiscovery(database: IntroducerDiscoveryDatabase, userId: string, limit?: number): Promise<ContactWithIntents[]>;
+/**
+ * Determine whether introducer discovery should run based on the current
+ * connector-flow composition. Triggers when connector-flow count is below
+ * the soft target.
+ *
+ * @param connectorFlowCount - Current number of connector-flow opportunities
+ * @param connectorFlowTarget - Soft target (default 2)
+ * @returns Whether introducer discovery should run
+ */
+export declare function shouldRunIntroducerDiscovery(connectorFlowCount: number, connectorFlowTarget?: number): boolean;
+/**
+ * Run introducer discovery for a user: select contacts, enqueue discovery jobs.
+ * Each job uses onBehalfOfUserId so the opportunity graph treats the user as introducer.
+ *
+ * @param database - Database adapter for contact queries
+ * @param queue - Queue for enqueuing discovery jobs
+ * @param userId - The introducer user
+ * @returns Summary of the discovery cycle
+ */
+export declare function runIntroducerDiscovery(database: IntroducerDiscoveryDatabase, queue: IntroducerDiscoveryQueue, userId: string): Promise<IntroducerDiscoveryResult>;

package/dist/opportunity/application/opportunity.introducer.js

@@ -0,0 +1,99 @@
+/**
+ * Introducer Discovery: proactive discovery of connector-flow opportunities
+ * between a user's contacts.
+ *
+ * Selects top-N contacts from the user's personal network and runs scoped
+ * HyDE discovery for each, creating latent introducer opportunities that
+ * the user (as introducer) must approve before parties see them.
+ */
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+const logger = protocolLogger('IntroducerDiscovery');
+/** Maximum contacts to evaluate per maintenance cycle. */
+export const MAX_CONTACTS_PER_CYCLE = 5;
+/** Maximum candidate opportunities per contact. */
+export const MAX_CANDIDATES_PER_CONTACT = 3;
+/** Detection source value for introducer-discovered opportunities. */
+export const INTRODUCER_DISCOVERY_SOURCE = 'introducer_discovery';
+/**
+ * Select top-N contacts for introducer discovery, sorted by intent freshness.
+ * Contacts with no active intents are excluded.
+ *
+ * @param database - Database adapter with contact/intent queries
+ * @param userId - The introducer user
+ * @param limit - Max contacts to return (default MAX_CONTACTS_PER_CYCLE)
+ * @returns Sorted contacts with intent data
+ */
+export async function selectContactsForDiscovery(database, userId, limit = MAX_CONTACTS_PER_CYCLE) {
+    const personalIndexId = await database.getPersonalIndexId(userId);
+    if (!personalIndexId) {
+        logger.verbose('No personal network found', { userId });
+        return [];
+    }
+    const contacts = await database.getContactsWithIntentFreshness(personalIndexId, userId, limit);
+    logger.verbose('Selected contacts for discovery', { userId, totalContacts: contacts.length, limit });
+    return contacts;
+}
+/**
+ * Determine whether introducer discovery should run based on the current
+ * connector-flow composition. Triggers when connector-flow count is below
+ * the soft target.
+ *
+ * @param connectorFlowCount - Current number of connector-flow opportunities
+ * @param connectorFlowTarget - Soft target (default 2)
+ * @returns Whether introducer discovery should run
+ */
+export function shouldRunIntroducerDiscovery(connectorFlowCount, connectorFlowTarget = 2) {
+    return connectorFlowCount < connectorFlowTarget;
+}
+/**
+ * Run introducer discovery for a user: select contacts, enqueue discovery jobs.
+ * Each job uses onBehalfOfUserId so the opportunity graph treats the user as introducer.
+ *
+ * @param database - Database adapter for contact queries
+ * @param queue - Queue for enqueuing discovery jobs
+ * @param userId - The introducer user
+ * @returns Summary of the discovery cycle
+ */
+export async function runIntroducerDiscovery(database, queue, userId) {
+    const personalIndexId = await database.getPersonalIndexId(userId);
+    if (!personalIndexId) {
+        return { contactsEvaluated: 0, jobsEnqueued: 0, skippedReason: 'no_personal_index' };
+    }
+    const contacts = await selectContactsForDiscovery(database, userId);
+    if (contacts.length === 0) {
+        return { contactsEvaluated: 0, jobsEnqueued: 0, skippedReason: 'no_contacts' };
+    }
+    const bucket = Math.floor(Date.now() / (12 * 60 * 60 * 1000)); // 12h dedup bucket
+    const results = await Promise.allSettled(contacts.map(async (contact) => {
+        // For each contact, we enqueue a discovery job using one of their intents
+        // The opportunity graph will use onBehalfOfUserId to discover on behalf of the contact
+        // while the userId (introducer) gets the introducer role
+        const jobId = `introducer-discovery-${userId}-${contact.userId}-${bucket}`;
+        try {
+            await queue.addJob({
+                intentId: `introducer:${contact.userId}`,
+                userId,
+                indexIds: [personalIndexId],
+                contactUserId: contact.userId,
+            }, { priority: 15, jobId });
+            return true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/duplicate|already exists|job.*id/i.test(message)) {
+                logger.verbose('Job skipped (duplicate)', { userId, contactUserId: contact.userId, error: message });
+                return false;
+            }
+            throw err;
+        }
+    }));
+    for (const r of results) {
+        if (r.status === 'rejected') {
+            const errMsg = r.reason instanceof Error ? r.reason.message : String(r.reason);
+            logger.error('Job enqueue failed', { error: errMsg });
+        }
+    }
+    const jobsEnqueued = results.filter((r) => r.status === 'fulfilled' && r.value).length;
+    logger.info('Discovery cycle complete', { userId, contactsEvaluated: contacts.length, jobsEnqueued });
+    return { contactsEvaluated: contacts.length, jobsEnqueued };
+}

package/dist/opportunity/application/opportunity.lifecycle.d.ts

@@ -0,0 +1,63 @@
+import type { Opportunity, OpportunityActor, OpportunityGraphDatabase } from '../../shared/interfaces/database.interface.js';
+/** The mutation result shape returned by opportunity lifecycle graph nodes. */
+export interface OpportunityMutationResult {
+    success: boolean;
+    message?: string;
+    opportunityId?: string;
+    notified?: string[];
+    conversationId?: string;
+    error?: string;
+}
+/** Narrow persistence boundary for user-driven opportunity lifecycle actions. */
+export type OpportunityLifecyclePort = Pick<OpportunityGraphDatabase, 'getOpportunity' | 'getOrCreateDM' | 'stampOpportunityActorAction' | 'updateOpportunityActorApproval' | 'updateOpportunityStatus'>;
+/** Host callback used to notify an actor after an opportunity becomes visible to them. */
+export type QueueOpportunityNotificationFn = (opportunityId: string, recipientId: string, priority: 'immediate' | 'high' | 'low') => Promise<unknown>;
+type StatusTransitionPlan = {
+    kind: 'stamp_accepted';
+    counterpartUserId?: string;
+} | {
+    kind: 'set_terminal_status';
+    status: 'rejected' | 'expired';
+};
+type SendOpportunityPlan = {
+    sender: OpportunityActor;
+    recipients: OpportunityActor[];
+};
+/**
+ * Applies status-transition admission rules before lifecycle persistence.
+ * Acceptance is a two-party action: an actor that already acted cannot accept
+ * again, while rejection and expiry remain available to any participating actor.
+ */
+export declare function assessOpportunityStatusTransition(opportunity: Opportunity, actorUserId: string, newStatus: string | undefined): StatusTransitionPlan | OpportunityMutationResult;
+/**
+ * Applies send admission and recipient-routing rules without performing writes.
+ * Introducers, peers, and direct patient/party flows each reveal the next tier
+ * to a distinct audience.
+ */
+export declare function assessOpportunitySend(opportunity: Opportunity, actorUserId: string): SendOpportunityPlan | OpportunityMutationResult;
+/** Checks whether a caller may approve this opportunity's introducer gate. */
+export declare function assessIntroductionApproval(opportunity: Opportunity, actorUserId: string): OpportunityMutationResult | {
+    kind: 'approve';
+};
+/** Persists an admitted status transition, preserving accept-before-write DM ordering. */
+export declare function updateOpportunityLifecycle(database: OpportunityLifecyclePort, input: {
+    opportunityId?: string;
+    actorUserId: string;
+    newStatus?: string;
+}): Promise<OpportunityMutationResult>;
+/** Expires an opportunity after verifying the caller is one of its actors. */
+export declare function deleteOpportunityLifecycle(database: OpportunityLifecyclePort, input: {
+    opportunityId?: string;
+    actorUserId: string;
+}): Promise<OpportunityMutationResult>;
+/** Persists a send transition, then notifies only the actors exposed by its routing policy. */
+export declare function sendOpportunityLifecycle(database: OpportunityLifecyclePort, input: {
+    opportunityId?: string;
+    actorUserId: string;
+}, queueNotification?: QueueOpportunityNotificationFn): Promise<OpportunityMutationResult>;
+/** Approves an introducer gate before enqueuing the existing-opportunity negotiation. */
+export declare function approveOpportunityIntroduction(database: OpportunityLifecyclePort, input: {
+    opportunityId?: string;
+    actorUserId: string;
+}, queueNegotiateExisting?: (opportunityId: string, userId: string) => Promise<void>): Promise<OpportunityMutationResult>;
+export {};

package/dist/opportunity/application/opportunity.lifecycle.js

@@ -0,0 +1,181 @@
+/**
+ * Applies status-transition admission rules before lifecycle persistence.
+ * Acceptance is a two-party action: an actor that already acted cannot accept
+ * again, while rejection and expiry remain available to any participating actor.
+ */
+export function assessOpportunityStatusTransition(opportunity, actorUserId, newStatus) {
+    if (newStatus !== 'accepted' && newStatus !== 'rejected' && newStatus !== 'expired') {
+        return { success: false, error: 'newStatus must be one of: accepted, rejected, expired.' };
+    }
+    const callerActor = opportunity.actors.find((actor) => actor.userId === actorUserId);
+    if (!callerActor) {
+        return { success: false, error: 'You are not part of this opportunity.' };
+    }
+    if (newStatus === 'accepted') {
+        if (callerActor.actedAt) {
+            return {
+                success: false,
+                error: 'You have already acted on this opportunity. The other party must accept.',
+            };
+        }
+        return {
+            kind: 'stamp_accepted',
+            counterpartUserId: opportunity.actors.find((actor) => actor.userId !== actorUserId && actor.role !== 'introducer')?.userId,
+        };
+    }
+    return { kind: 'set_terminal_status', status: newStatus };
+}
+/**
+ * Applies send admission and recipient-routing rules without performing writes.
+ * Introducers, peers, and direct patient/party flows each reveal the next tier
+ * to a distinct audience.
+ */
+export function assessOpportunitySend(opportunity, actorUserId) {
+    if (opportunity.status !== 'latent' && opportunity.status !== 'draft') {
+        return {
+            success: false,
+            error: `Opportunity is already ${opportunity.status}; only latent or draft opportunities can be sent.`,
+        };
+    }
+    const sender = opportunity.actors.find((actor) => actor.userId === actorUserId);
+    if (!sender) {
+        return { success: false, error: 'You are not part of this opportunity.' };
+    }
+    const hasIntroducer = opportunity.actors.some((actor) => actor.role === 'introducer');
+    const canSend = sender.role === 'introducer'
+        || sender.role === 'peer'
+        || (sender.role === 'patient' && !hasIntroducer)
+        || (sender.role === 'party' && !hasIntroducer);
+    if (!canSend) {
+        return { success: false, error: 'You cannot send this opportunity.' };
+    }
+    const recipients = sender.role === 'introducer'
+        ? opportunity.actors.filter((actor) => actor.role === 'patient' || actor.role === 'party')
+        : sender.role === 'peer'
+            ? opportunity.actors.filter((actor) => actor.role === 'peer' && actor.userId !== actorUserId)
+            : opportunity.actors.filter((actor) => actor.role === 'agent');
+    return { sender, recipients };
+}
+/** Checks whether a caller may approve this opportunity's introducer gate. */
+export function assessIntroductionApproval(opportunity, actorUserId) {
+    const introducerActor = opportunity.actors.find((actor) => actor.role === 'introducer' && actor.userId === actorUserId);
+    if (!introducerActor) {
+        return { success: false, error: 'You are not the introducer for this opportunity' };
+    }
+    if (introducerActor.approved === true) {
+        return { success: false, error: 'Introduction already approved' };
+    }
+    return { kind: 'approve' };
+}
+function isMutationResult(value) {
+    return 'success' in value;
+}
+/** Persists an admitted status transition, preserving accept-before-write DM ordering. */
+export async function updateOpportunityLifecycle(database, input) {
+    if (!input.opportunityId) {
+        return { success: false, error: 'opportunityId is required.' };
+    }
+    // Preserve the graph's legacy validation order: invalid transitions do not
+    // read persistence and always return the input error before actor checks.
+    if (input.newStatus !== 'accepted' && input.newStatus !== 'rejected' && input.newStatus !== 'expired') {
+        return { success: false, error: 'newStatus must be one of: accepted, rejected, expired.' };
+    }
+    const opportunity = await database.getOpportunity(input.opportunityId);
+    if (!opportunity) {
+        return { success: false, error: 'Opportunity not found.' };
+    }
+    const plan = assessOpportunityStatusTransition(opportunity, input.actorUserId, input.newStatus);
+    if (isMutationResult(plan))
+        return plan;
+    let conversationId;
+    if (plan.kind === 'stamp_accepted') {
+        if (plan.counterpartUserId) {
+            const dm = await database.getOrCreateDM(input.actorUserId, plan.counterpartUserId);
+            conversationId = dm.id;
+        }
+        await database.stampOpportunityActorAction(input.opportunityId, input.actorUserId, 'accepted', input.actorUserId);
+    }
+    else {
+        await database.updateOpportunityStatus(input.opportunityId, plan.status);
+    }
+    return {
+        success: true,
+        opportunityId: input.opportunityId,
+        message: `Opportunity status updated to ${input.newStatus}.`,
+        ...(conversationId && { conversationId }),
+    };
+}
+/** Expires an opportunity after verifying the caller is one of its actors. */
+export async function deleteOpportunityLifecycle(database, input) {
+    if (!input.opportunityId) {
+        return { success: false, error: 'opportunityId is required.' };
+    }
+    const opportunity = await database.getOpportunity(input.opportunityId);
+    if (!opportunity) {
+        return { success: false, error: 'Opportunity not found.' };
+    }
+    if (!opportunity.actors.some((actor) => actor.userId === input.actorUserId)) {
+        return { success: false, error: 'You are not part of this opportunity.' };
+    }
+    await database.updateOpportunityStatus(input.opportunityId, 'expired');
+    return {
+        success: true,
+        opportunityId: input.opportunityId,
+        message: 'Opportunity archived (expired).',
+    };
+}
+/** Persists a send transition, then notifies only the actors exposed by its routing policy. */
+export async function sendOpportunityLifecycle(database, input, queueNotification) {
+    if (!input.opportunityId) {
+        return { success: false, error: 'opportunityId is required.' };
+    }
+    const opportunity = await database.getOpportunity(input.opportunityId);
+    if (!opportunity) {
+        return { success: false, error: 'Opportunity not found.' };
+    }
+    const plan = assessOpportunitySend(opportunity, input.actorUserId);
+    if (isMutationResult(plan))
+        return plan;
+    await database.stampOpportunityActorAction(input.opportunityId, input.actorUserId, 'pending');
+    if (queueNotification) {
+        for (const recipient of plan.recipients) {
+            await queueNotification(opportunity.id, recipient.userId, 'high');
+        }
+    }
+    return {
+        success: true,
+        opportunityId: opportunity.id,
+        notified: plan.recipients.map((actor) => actor.userId),
+        message: 'Opportunity sent. The other person has been notified.',
+    };
+}
+/** Approves an introducer gate before enqueuing the existing-opportunity negotiation. */
+export async function approveOpportunityIntroduction(database, input, queueNegotiateExisting) {
+    if (!input.opportunityId) {
+        return { success: false, error: 'opportunityId required for approve_introduction' };
+    }
+    let opportunity;
+    try {
+        opportunity = await database.getOpportunity(input.opportunityId);
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to load opportunity: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!opportunity) {
+        return { success: false, error: 'Opportunity not found' };
+    }
+    const admission = assessIntroductionApproval(opportunity, input.actorUserId);
+    if (isMutationResult(admission))
+        return admission;
+    const updated = await database.updateOpportunityActorApproval(input.opportunityId, input.actorUserId, true);
+    if (!updated) {
+        return { success: false, error: 'Failed to update approval' };
+    }
+    if (queueNegotiateExisting) {
+        await queueNegotiateExisting(input.opportunityId, input.actorUserId);
+    }
+    return { success: true, opportunityId: input.opportunityId };
+}

package/dist/opportunity/application/opportunity.newborn-stamping.d.ts

@@ -0,0 +1,41 @@
+import type { CreateOpportunityData } from '../../shared/interfaces/database.interface.js';
+/** Input for the host-side newborn pool-preference stamper (IND-420 P4b). */
+export interface StampNewbornOpportunitiesInput {
+    ownerUserId: string;
+    intentId: string;
+    items: CreateOpportunityData[];
+}
+/**
+ * Optional host callback that stamps call-local create items before INSERT.
+ * It must preserve array length/order and may only enrich metadata/signals.
+ */
+export type StampNewbornOpportunitiesFn = (input: StampNewbornOpportunitiesInput) => Promise<CreateOpportunityData[]>;
+/** Persist-node facts that determine whether a new item may cross the host stamping boundary. */
+export interface NewbornStampingEligibility {
+    ownerUserId: string;
+    operationMode?: string;
+    hasIntroductionContext: boolean;
+    onBehalfOfUserId?: string;
+    targetUserId?: string;
+    discoverySource?: string;
+    resolvedTriggerIntentId?: string;
+    indexedIntentIds: readonly string[];
+}
+/** Fail-open events are injected so the graph retains its owning observability policy. */
+export interface NewbornStampingObserver {
+    onUnsafeResult?: (details: {
+        expected: number;
+        actual: number | null;
+    }) => void;
+    onFailure?: (details: {
+        intentId: string;
+        error: unknown;
+    }) => void;
+}
+/**
+ * Stamps only newly-created, owned-intent discovery items. Reactivations and
+ * manual, introducer, on-behalf-of, context-only, and continuation flows never
+ * cross this host boundary. Unsafe callback output and callback failures retain
+ * the original create items without changing their order.
+ */
+export declare function stampEligibleNewbornOpportunities(itemsToPersist: CreateOpportunityData[], eligibility: NewbornStampingEligibility, stamper?: StampNewbornOpportunitiesFn, observer?: NewbornStampingObserver): Promise<CreateOpportunityData[]>;

package/dist/opportunity/application/opportunity.newborn-stamping.js

@@ -0,0 +1,81 @@
+function copyCreateOpportunityData(item) {
+    return {
+        ...item,
+        detection: { ...item.detection },
+        actors: item.actors.map((actor) => ({ ...actor })),
+        interpretation: {
+            ...item.interpretation,
+            signals: item.interpretation.signals?.map((signal) => ({ ...signal })),
+        },
+        context: { ...item.context },
+        metadata: item.metadata ? { ...item.metadata } : item.metadata,
+    };
+}
+/** Fields a stamper is not allowed to change; this also protects candidate order. */
+function newbornItemIdentity(item) {
+    return JSON.stringify({
+        detection: item.detection,
+        actors: item.actors,
+        interpretation: {
+            category: item.interpretation.category,
+            reasoning: item.interpretation.reasoning,
+            confidence: item.interpretation.confidence,
+        },
+        context: item.context,
+        confidence: item.confidence,
+        status: item.status,
+        expiresAt: item.expiresAt?.toISOString(),
+    });
+}
+/**
+ * Stamps only newly-created, owned-intent discovery items. Reactivations and
+ * manual, introducer, on-behalf-of, context-only, and continuation flows never
+ * cross this host boundary. Unsafe callback output and callback failures retain
+ * the original create items without changing their order.
+ */
+export async function stampEligibleNewbornOpportunities(itemsToPersist, eligibility, stamper, observer) {
+    const stampIntentId = eligibility.resolvedTriggerIntentId;
+    const mayStamp = Boolean(stamper
+        && eligibility.operationMode === 'create'
+        && !eligibility.hasIntroductionContext
+        && !eligibility.onBehalfOfUserId
+        && !eligibility.targetUserId
+        && eligibility.discoverySource === 'intent'
+        && stampIntentId
+        && eligibility.indexedIntentIds.includes(stampIntentId));
+    if (!mayStamp || !stampIntentId || itemsToPersist.length === 0 || !stamper) {
+        return itemsToPersist;
+    }
+    const eligibleIndexes = itemsToPersist.flatMap((item, index) => item.detection.source === 'opportunity_graph' && item.detection.triggeredBy === stampIntentId
+        ? [index]
+        : []);
+    if (eligibleIndexes.length === 0)
+        return itemsToPersist;
+    const originals = eligibleIndexes.map((index) => itemsToPersist[index]);
+    try {
+        const stamped = await stamper({
+            ownerUserId: eligibility.ownerUserId,
+            intentId: stampIntentId,
+            items: originals.map(copyCreateOpportunityData),
+        });
+        const valid = Array.isArray(stamped)
+            && stamped.length === originals.length
+            && stamped.every((item, index) => newbornItemIdentity(item) === newbornItemIdentity(originals[index]));
+        if (!valid) {
+            observer?.onUnsafeResult?.({
+                expected: originals.length,
+                actual: Array.isArray(stamped) ? stamped.length : null,
+            });
+            return itemsToPersist;
+        }
+        const itemsForPersistence = [...itemsToPersist];
+        eligibleIndexes.forEach((itemIndex, stampedIndex) => {
+            itemsForPersistence[itemIndex] = stamped[stampedIndex];
+        });
+        return itemsForPersistence;
+    }
+    catch (error) {
+        observer?.onFailure?.({ intentId: stampIntentId, error });
+        return itemsToPersist;
+    }
+}

package/dist/opportunity/application/opportunity.pending-questions.d.ts

@@ -0,0 +1,33 @@
+import type { PendingQuestionSummary } from "../../shared/schemas/pending-question.schema.js";
+/** Maximum pending questions attached to a single tool result. */
+export declare const MAX_PENDING_QUESTIONS = 3;
+export interface MergePendingQuestionsInput {
+    findPendingQuestions?: (userId: string, filters?: {
+        sourceType?: string;
+        sourceId?: string;
+        networkId?: string;
+        scopeType?: 'intent';
+        scopeId?: string;
+    }) => Promise<PendingQuestionSummary[]>;
+    userId: string;
+    sourceType?: string;
+    sourceId?: string;
+    /** Restrict to questions whose actor carries this network id. */
+    networkId?: string;
+    /** Optional selected-intent scope. */
+    scopeType?: 'intent';
+    scopeId?: string;
+    /** IDs already shown in this chat session — skip them. */
+    surfacedQuestionIds: Set<string>;
+}
+export interface MergePendingQuestionsResult {
+    /** Questions to attach to the tool result (under the `questions` key). */
+    questions: PendingQuestionSummary[];
+    /** IDs of the questions that were included (caller should add to surfacedQuestionIds). */
+    surfacedIds: string[];
+}
+/**
+ * Query pending questions and filter out already-surfaced ones.
+ * Returns at most MAX_PENDING_QUESTIONS entries.
+ */
+export declare function mergePendingQuestions(input: MergePendingQuestionsInput): Promise<MergePendingQuestionsResult>;

package/dist/opportunity/application/opportunity.pending-questions.js

@@ -0,0 +1,42 @@
+/**
+ * Helper for merging pending questions from the DB into tool results.
+ * Extracted so it can be unit-tested independently of the tool handler.
+ */
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+const logger = protocolLogger("PendingQuestions");
+/** Maximum pending questions attached to a single tool result. */
+export const MAX_PENDING_QUESTIONS = 3;
+/**
+ * Query pending questions and filter out already-surfaced ones.
+ * Returns at most MAX_PENDING_QUESTIONS entries.
+ */
+export async function mergePendingQuestions(input) {
+    if (!input.findPendingQuestions) {
+        return { questions: [], surfacedIds: [] };
+    }
+    const hasFilters = Boolean(input.sourceType || input.networkId || input.scopeType);
+    const filters = hasFilters
+        ? {
+            ...(input.sourceType ? { sourceType: input.sourceType } : {}),
+            ...(input.sourceId ? { sourceId: input.sourceId } : {}),
+            ...(input.networkId ? { networkId: input.networkId } : {}),
+            ...(input.scopeType && input.scopeId ? { scopeType: input.scopeType, scopeId: input.scopeId } : {}),
+        }
+        : undefined;
+    let pending;
+    try {
+        pending = await input.findPendingQuestions(input.userId, filters);
+    }
+    catch (err) {
+        logger.warn('Failed to fetch pending questions, returning empty', { error: err });
+        return { questions: [], surfacedIds: [] };
+    }
+    // Deduplicate against already-surfaced IDs in this session
+    const fresh = pending.filter((q) => !input.surfacedQuestionIds.has(q.id));
+    const capped = fresh.slice(0, MAX_PENDING_QUESTIONS);
+    const publicQuestions = capped.map(({ actors: _actors, purpose: _purpose, ...question }) => question);
+    return {
+        questions: publicQuestions,
+        surfacedIds: capped.map((q) => q.id),
+    };
+}