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

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

@@ -0,0 +1,63 @@
+/**
+ * opportunity/application — LLM agents, LangGraph graphs, effectful orchestration.
+ *
+ * ## What lives here (flat files)
+ * - Opportunity lifecycle transitions (opportunity.lifecycle.ts)
+ * - Enricher: merge overlapping opportunities (opportunity.enricher.ts)
+ * - Persistence coordinator (opportunity.persist.ts)
+ * - Persistence admission gate (opportunity.persistence-admission.ts)
+ * - Update admission gate (opportunity.update-admission.ts)
+ * - Newborn-opportunity stamping (opportunity.newborn-stamping.ts)
+ * - LLM evaluator (opportunity.evaluator.ts)
+ * - LLM presenter agent (opportunity.presenter.ts)
+ * - Introducer discovery (opportunity.introducer.ts)
+ * - Existing-negotiation path (opportunity.existing-negotiation.ts)
+ * - Opportunity LangGraph (opportunity.graph.ts)
+ * - MCP discover flow (opportunity.discover.ts)
+ * - Card presentation builder (opportunity.card-presentation.ts)
+ * - Discovery continuation finalization (opportunity.discovery-continuation-finalization.ts)
+ * - MCP lifecycle finalization (opportunity.discovery-mcp-lifecycle-finalization.ts)
+ * - Negotiation summary helper (opportunity.discovery-negotiation-summary.ts)
+ * - Negotiation context loader (negotiation-context.loader.ts)
+ * - Feed selection (opportunity.feed-selection.ts)
+ * - Delivery card cache (delivery-card.cache.ts)
+ * - Pending questions merger (opportunity.pending-questions.ts)
+ *
+ * ## What lives in subdirectories (exported by path, not moved)
+ * - discriminator/ — miner, assigner, shadow orchestrator
+ * - negotiation-evidence/ — miner, shadow orchestrator
+ * - outcome/ — shadow orchestrator
+ * - feed/ — home feed categorizer and graph
+ *
+ * IND-551: canonical application layer for the opportunities capability.
+ */
+export * from "./opportunity.lifecycle.js";
+export * from "./opportunity.enricher.js";
+export * from "./opportunity.persist.js";
+export * from "./opportunity.persistence-admission.js";
+export * from "./opportunity.update-admission.js";
+export * from "./opportunity.newborn-stamping.js";
+export * from "./opportunity.evaluator.js";
+export * from "./opportunity.presenter.js";
+export * from "./opportunity.introducer.js";
+export * from "./opportunity.existing-negotiation.js";
+export * from "./opportunity.graph.js";
+export * from "./opportunity.discover.js";
+export * from "./opportunity.card-presentation.js";
+export * from "./opportunity.discovery-continuation-finalization.js";
+export * from "./opportunity.discovery-mcp-lifecycle-finalization.js";
+export * from "./opportunity.discovery-negotiation-summary.js";
+export * from "./negotiation-context.loader.js";
+export * from "./opportunity.feed-selection.js";
+export * from "./delivery-card.cache.js";
+export * from "./opportunity.pending-questions.js";
+export * from "./opportunity.tools.js";
+export { PoolDiscriminatorMiner } from "../discriminator/discriminator.miner.js";
+export { PoolDiscriminatorAssigner, } from "../discriminator/discriminator.assigner.js";
+export type { PoolDiscriminatorAssignmentInput, PoolDiscriminatorAssignedAxis, } from "../discriminator/discriminator.assigner.js";
+export { runPoolDiscriminatorShadow } from "../discriminator/discriminator.shadow.js";
+export { NegotiationEvidenceMiner } from "../negotiation-evidence/negotiation-evidence.miner.js";
+export { runNegotiationEvidenceShadow } from "../negotiation-evidence/negotiation-evidence.shadow.js";
+export { runOutcomeShadow } from "../outcome/outcome.shadow.js";
+export { HomeGraphFactory } from "../feed/feed.graph.js";
+export { HomeCategorizerAgent } from "../feed/feed.categorizer.js";

package/dist/opportunity/application/index.js

@@ -0,0 +1,68 @@
+/**
+ * opportunity/application — LLM agents, LangGraph graphs, effectful orchestration.
+ *
+ * ## What lives here (flat files)
+ * - Opportunity lifecycle transitions (opportunity.lifecycle.ts)
+ * - Enricher: merge overlapping opportunities (opportunity.enricher.ts)
+ * - Persistence coordinator (opportunity.persist.ts)
+ * - Persistence admission gate (opportunity.persistence-admission.ts)
+ * - Update admission gate (opportunity.update-admission.ts)
+ * - Newborn-opportunity stamping (opportunity.newborn-stamping.ts)
+ * - LLM evaluator (opportunity.evaluator.ts)
+ * - LLM presenter agent (opportunity.presenter.ts)
+ * - Introducer discovery (opportunity.introducer.ts)
+ * - Existing-negotiation path (opportunity.existing-negotiation.ts)
+ * - Opportunity LangGraph (opportunity.graph.ts)
+ * - MCP discover flow (opportunity.discover.ts)
+ * - Card presentation builder (opportunity.card-presentation.ts)
+ * - Discovery continuation finalization (opportunity.discovery-continuation-finalization.ts)
+ * - MCP lifecycle finalization (opportunity.discovery-mcp-lifecycle-finalization.ts)
+ * - Negotiation summary helper (opportunity.discovery-negotiation-summary.ts)
+ * - Negotiation context loader (negotiation-context.loader.ts)
+ * - Feed selection (opportunity.feed-selection.ts)
+ * - Delivery card cache (delivery-card.cache.ts)
+ * - Pending questions merger (opportunity.pending-questions.ts)
+ *
+ * ## What lives in subdirectories (exported by path, not moved)
+ * - discriminator/ — miner, assigner, shadow orchestrator
+ * - negotiation-evidence/ — miner, shadow orchestrator
+ * - outcome/ — shadow orchestrator
+ * - feed/ — home feed categorizer and graph
+ *
+ * IND-551: canonical application layer for the opportunities capability.
+ */
+// ── Flat application files ────────────────────────────────────────────────────
+export * from "./opportunity.lifecycle.js";
+export * from "./opportunity.enricher.js";
+export * from "./opportunity.persist.js";
+export * from "./opportunity.persistence-admission.js";
+export * from "./opportunity.update-admission.js";
+export * from "./opportunity.newborn-stamping.js";
+export * from "./opportunity.evaluator.js";
+export * from "./opportunity.presenter.js";
+export * from "./opportunity.introducer.js";
+export * from "./opportunity.existing-negotiation.js";
+export * from "./opportunity.graph.js";
+export * from "./opportunity.discover.js";
+export * from "./opportunity.card-presentation.js";
+export * from "./opportunity.discovery-continuation-finalization.js";
+export * from "./opportunity.discovery-mcp-lifecycle-finalization.js";
+export * from "./opportunity.discovery-negotiation-summary.js";
+export * from "./negotiation-context.loader.js";
+export * from "./opportunity.feed-selection.js";
+export * from "./delivery-card.cache.js";
+export * from "./opportunity.pending-questions.js";
+export * from "./opportunity.tools.js";
+// ── Subdirectory application exports ─────────────────────────────────────────
+// discriminator application
+export { PoolDiscriminatorMiner } from "../discriminator/discriminator.miner.js";
+export { PoolDiscriminatorAssigner, } from "../discriminator/discriminator.assigner.js";
+export { runPoolDiscriminatorShadow } from "../discriminator/discriminator.shadow.js";
+// negotiation-evidence application
+export { NegotiationEvidenceMiner } from "../negotiation-evidence/negotiation-evidence.miner.js";
+export { runNegotiationEvidenceShadow } from "../negotiation-evidence/negotiation-evidence.shadow.js";
+// outcome application
+export { runOutcomeShadow } from "../outcome/outcome.shadow.js";
+// feed application
+export { HomeGraphFactory } from "../feed/feed.graph.js";
+export { HomeCategorizerAgent } from "../feed/feed.categorizer.js";

package/dist/opportunity/application/negotiation-context.loader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Negotiation context loader: given an opportunity, fetches the attached
+ * negotiation task's transcript and outcome so the home-card presenter can
+ * explain *why* the opportunity surfaced.
+ *
+ * For `draft`, `latent`, and `expired` opportunities, no negotiation has
+ * happened (or no longer matters) so the loader returns null.
+ *
+ * For `negotiating` opportunities, only `turnCount` / `turnCap` are returned
+ * — the presenter renders a templated chip without invoking the LLM.
+ *
+ * For `pending`, `stalled`, `accepted`, and `rejected` opportunities, the
+ * full transcript and outcome are included so the prompt can ground its
+ * explanation in concrete turn content.
+ *
+ * Screened-out negotiations (P2.2 — the client's own outreach gate declined
+ * before any turn was exchanged) return null: presentation treats them as
+ * never-happened, so no card, feed, or digest surface can frame the client's
+ * private gate decision as a "counterparty declined" event.
+ */
+import type { NegotiationGraphDatabase, OpportunityStatus } from '../../shared/interfaces/database.interface.js';
+import type { NegotiationOutcome, NegotiationTurn } from '../../capabilities/negotiation.state.facade.js';
+/**
+ * Narrow slice of {@link NegotiationGraphDatabase} required by the loader. Kept
+ * minimal so call sites can opt into a smaller surface.
+ */
+export type NegotiationContextDatabase = Pick<NegotiationGraphDatabase, 'getNegotiationTaskForOpportunity' | 'getMessagesForConversation' | 'getArtifactsForTask'>;
+/**
+ * Snapshot of a negotiation surfaced to the presenter. `turns` and `outcome`
+ * are only populated for post-negotiation statuses (pending/stalled/
+ * accepted/rejected); `negotiating` gets only the counters.
+ */
+export interface NegotiationContext {
+    status: OpportunityStatus;
+    /**
+     * Conversation/task id of the A2A negotiation that produced this opportunity.
+     * Lets callers deep-link to the negotiation trace (e.g. `/chat/:conversationId`).
+     * Present whenever a negotiation task exists (i.e. context is non-null).
+     */
+    conversationId: string;
+    turnCount: number;
+    /** Max turns allowed for this negotiation (0 = unlimited). */
+    turnCap: number;
+    /** Only present when status is not `negotiating`. */
+    outcome?: NegotiationOutcome;
+    /** Only present when status is not `negotiating`. */
+    turns?: NegotiationTurn[];
+}
+/**
+ * Loads the negotiation context for an opportunity.
+ *
+ * @param db - Narrow slice of NegotiationGraphDatabase.
+ * @param opportunityId - Opportunity to load negotiation context for.
+ * @param opportunityStatus - Current opportunity status. Used to gate loading
+ *   and to decide which fields to populate.
+ * @returns NegotiationContext, or null when no meaningful negotiation exists
+ *   (draft/latent/expired) or when the task lookup fails.
+ */
+export declare function loadNegotiationContext(db: NegotiationContextDatabase, opportunityId: string, opportunityStatus: OpportunityStatus): Promise<NegotiationContext | null>;

package/dist/opportunity/application/negotiation-context.loader.js

@@ -0,0 +1,88 @@
+/**
+ * Negotiation context loader: given an opportunity, fetches the attached
+ * negotiation task's transcript and outcome so the home-card presenter can
+ * explain *why* the opportunity surfaced.
+ *
+ * For `draft`, `latent`, and `expired` opportunities, no negotiation has
+ * happened (or no longer matters) so the loader returns null.
+ *
+ * For `negotiating` opportunities, only `turnCount` / `turnCap` are returned
+ * — the presenter renders a templated chip without invoking the LLM.
+ *
+ * For `pending`, `stalled`, `accepted`, and `rejected` opportunities, the
+ * full transcript and outcome are included so the prompt can ground its
+ * explanation in concrete turn content.
+ *
+ * Screened-out negotiations (P2.2 — the client's own outreach gate declined
+ * before any turn was exchanged) return null: presentation treats them as
+ * never-happened, so no card, feed, or digest surface can frame the client's
+ * private gate decision as a "counterparty declined" event.
+ */
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+const logger = protocolLogger('NegotiationContextLoader');
+const STATUSES_WITH_NO_NEGOTIATION = ['draft', 'latent', 'expired'];
+const NEGOTIATION_OUTCOME_ARTIFACT_NAME = 'negotiation-outcome';
+/**
+ * Loads the negotiation context for an opportunity.
+ *
+ * @param db - Narrow slice of NegotiationGraphDatabase.
+ * @param opportunityId - Opportunity to load negotiation context for.
+ * @param opportunityStatus - Current opportunity status. Used to gate loading
+ *   and to decide which fields to populate.
+ * @returns NegotiationContext, or null when no meaningful negotiation exists
+ *   (draft/latent/expired) or when the task lookup fails.
+ */
+export async function loadNegotiationContext(db, opportunityId, opportunityStatus) {
+    if (STATUSES_WITH_NO_NEGOTIATION.includes(opportunityStatus)) {
+        return null;
+    }
+    const task = await db.getNegotiationTaskForOpportunity(opportunityId);
+    if (!task) {
+        logger.verbose('No negotiation task found for opportunity', { opportunityId, opportunityStatus });
+        return null;
+    }
+    const turnCap = readNumber(task.metadata, 'maxTurns') ?? 0;
+    const messages = await db.getMessagesForConversation(task.conversationId);
+    const turns = extractTurns(messages);
+    const turnCount = turns.length;
+    if (opportunityStatus === 'negotiating') {
+        return { status: opportunityStatus, conversationId: task.conversationId, turnCount, turnCap };
+    }
+    const artifacts = await db.getArtifactsForTask(task.id);
+    const outcome = extractOutcome(artifacts);
+    // P2.2: screened_out is the client's private gate decision, not a negotiation.
+    if (outcome?.reason === 'screened_out') {
+        return null;
+    }
+    return {
+        status: opportunityStatus,
+        conversationId: task.conversationId,
+        turnCount,
+        turnCap,
+        ...(outcome ? { outcome } : {}),
+        turns,
+    };
+}
+function readNumber(metadata, key) {
+    if (!metadata)
+        return undefined;
+    const value = metadata[key];
+    return typeof value === 'number' ? value : undefined;
+}
+function extractTurns(messages) {
+    const turns = [];
+    for (const message of messages) {
+        const dataPart = message.parts.find((p) => p.kind === 'data');
+        if (dataPart?.data) {
+            turns.push(dataPart.data);
+        }
+    }
+    return turns;
+}
+function extractOutcome(artifacts) {
+    const outcomeArtifact = artifacts.find((a) => a.name === NEGOTIATION_OUTCOME_ARTIFACT_NAME);
+    if (!outcomeArtifact)
+        return undefined;
+    const dataPart = outcomeArtifact.parts.find((p) => p.kind === 'data');
+    return dataPart?.data;
+}

package/dist/opportunity/application/opportunity.card-presentation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal shape consumed by buildOpportunityPresentation for prose rendering.
+ * Card data objects in the codebase carry additional frontend-only fields;
+ * only these are surfaced to MCP agents.
+ */
+export type OpportunityCardLike = Record<string, unknown> & {
+    opportunityId: string;
+    userId?: string | undefined;
+    name?: string | undefined;
+    mainText?: string | undefined;
+    digestSummary?: string | undefined;
+    status?: string | undefined;
+    feedCategory?: string | undefined;
+    acceptUrl?: string | undefined;
+    profileUrl?: string | undefined;
+    /** Deep-link to the A2A negotiation trace that produced this opportunity. */
+    negotiationUrl?: string | undefined;
+    score?: number | undefined;
+    /** Digest-mode cooldown re-show — the user has seen this card before. */
+    redelivery?: boolean | undefined;
+};
+/**
+ * Format opportunity cards into the "opportunities" portion of a tool response.
+ *
+ * Web chat (`isMcp=false`): emits ```opportunity``` code fences with an
+ * "include EXACTLY as-is" directive so the frontend card renderer can parse
+ * and render interactive cards.
+ *
+ * MCP (`isMcp=true`): emits prose (name, reason, status, profileUrl when
+ * present, acceptUrl when present, feedCategory when present) and includes
+ * `opportunityId` ONLY for cards without an `acceptUrl` — exposing the UUID
+ * alongside an actionable link gave LLMs a foothold to hallucinate bare
+ * `/api/opportunities/<id>/connect` URLs (see IND-271). The trailing
+ * instruction reminds the agent to synthesize in natural language and never
+ * fabricate URLs for cards that don't have them. MCP clients have no card
+ * renderer, so code fences would surface as raw JSON to end users.
+ */
+export declare function buildOpportunityPresentation(inputCards: OpportunityCardLike[], opts: {
+    isMcp: boolean;
+    leadIn: string;
+    label?: 'opportunity' | 'opportunities';
+    /** Include hidden digest metadata markers so scheduled brief tooling can confirm delivery. */
+    includeDigestMarkers?: boolean;
+}): string;

package/dist/opportunity/application/opportunity.card-presentation.js

@@ -0,0 +1,104 @@
+import { stripUnsupportedOpportunityClaims } from '../domain/opportunity.claim-safety.js';
+import { stripUuids } from '../domain/opportunity.presentation.js';
+const CODE_FENCE = String.fromCharCode(96, 96, 96);
+function sanitizeJsonForCodeFence(json) {
+    return json.replace(/`/g, '\\u0060');
+}
+function sanitizeOpportunityCardProse(card) {
+    const sanitized = { ...card };
+    for (const key of ['mainText', 'digestSummary', 'headline', 'cta', 'mutualIntentsLabel']) {
+        const value = card[key];
+        if (typeof value === 'string') {
+            sanitized[key] = stripUnsupportedOpportunityClaims(stripUuids(value)) || 'A suggested connection.';
+        }
+    }
+    const narratorChip = card.narratorChip;
+    if (narratorChip && typeof narratorChip === 'object' && !Array.isArray(narratorChip)) {
+        const narrator = narratorChip;
+        if (typeof narrator.text === 'string') {
+            sanitized.narratorChip = {
+                ...narrator,
+                text: stripUnsupportedOpportunityClaims(stripUuids(narrator.text)) || 'A potential connection worth exploring.',
+            };
+        }
+    }
+    return sanitized;
+}
+/**
+ * Format opportunity cards into the "opportunities" portion of a tool response.
+ *
+ * Web chat (`isMcp=false`): emits ```opportunity``` code fences with an
+ * "include EXACTLY as-is" directive so the frontend card renderer can parse
+ * and render interactive cards.
+ *
+ * MCP (`isMcp=true`): emits prose (name, reason, status, profileUrl when
+ * present, acceptUrl when present, feedCategory when present) and includes
+ * `opportunityId` ONLY for cards without an `acceptUrl` — exposing the UUID
+ * alongside an actionable link gave LLMs a foothold to hallucinate bare
+ * `/api/opportunities/<id>/connect` URLs (see IND-271). The trailing
+ * instruction reminds the agent to synthesize in natural language and never
+ * fabricate URLs for cards that don't have them. MCP clients have no card
+ * renderer, so code fences would surface as raw JSON to end users.
+ */
+export function buildOpportunityPresentation(inputCards, opts) {
+    const cards = inputCards.map(sanitizeOpportunityCardProse);
+    if (cards.length === 0)
+        return opts.leadIn;
+    if (opts.isMcp) {
+        const prose = cards
+            .map((card, i) => {
+            const lines = [`${i + 1}. ${card.name ?? "Unknown"}`];
+            if (opts.includeDigestMarkers) {
+                const markerId = String(card.opportunityId).replace(/[\s>]/g, "");
+                if (markerId)
+                    lines.push(`   <!-- digest-opportunity:id=${markerId} -->`);
+            }
+            if (opts.includeDigestMarkers && card.digestSummary) {
+                lines.push(`   ${card.digestSummary}`);
+            }
+            else if (card.mainText) {
+                lines.push(`   ${card.mainText}`);
+            }
+            if (card.status)
+                lines.push(`   status: ${card.status}`);
+            if (card.profileUrl)
+                lines.push(`   profileUrl: ${card.profileUrl}`);
+            if (card.acceptUrl)
+                lines.push(`   acceptUrl: ${card.acceptUrl}`);
+            if (opts.includeDigestMarkers && card.negotiationUrl)
+                lines.push(`   negotiationUrl: ${card.negotiationUrl}`);
+            if (card.feedCategory)
+                lines.push(`   feedCategory: ${card.feedCategory}`);
+            if (opts.includeDigestMarkers && card.score != null)
+                lines.push(`   confidence: ${Math.round(card.score * 100)}`);
+            if (opts.includeDigestMarkers && card.redelivery)
+                lines.push(`   redelivery: true`);
+            // Only surface opportunityId when there's no acceptUrl. Exposing the
+            // UUID alongside an actionable link gives the LLM a foothold to
+            // hallucinate bare `/api/opportunities/<id>/connect` URLs.
+            if (!card.acceptUrl) {
+                lines.push(`   opportunityId: ${card.opportunityId}`);
+            }
+            return lines.join("\n");
+        })
+            .join("\n\n");
+        const hasLinks = cards.some((c) => c.acceptUrl);
+        const hasOpportunityIds = cards.some((c) => !c.acceptUrl);
+        const linkInstructions = hasLinks
+            ? `For each card that has an acceptUrl, embed it on a short verb phrase (e.g. "message [Name]" for connection, "make intro" for connector-flow). For each card that has a profileUrl, link the person's name to it. Some cards may have neither — render those as plain text and never fabricate URLs for them. The acceptUrl is opaque and self-contained — embed it verbatim. Do NOT append, encode, or modify any part of any URL. Never render link strips or tables — weave URLs into prose. `
+            : "";
+        const idInstructions = hasOpportunityIds
+            ? `Use opportunityId values only when calling update_opportunity (send/accept/reject) or confirm_opportunity_delivery.`
+            : "";
+        return (`${opts.leadIn}\n\n${prose}\n\n` +
+            `Summarize these for the user in natural prose — mention first names and a brief match reason per connection. ` +
+            `${linkInstructions}` +
+            `Do NOT print raw JSON, field labels, or opportunityIds. ` +
+            `${idInstructions}`);
+    }
+    const label = opts.label ?? (cards.length === 1 ? "opportunity" : "opportunities");
+    const blocks = cards
+        .map((card) => CODE_FENCE + "opportunity\n" + sanitizeJsonForCodeFence(JSON.stringify(card)) + "\n" + CODE_FENCE)
+        .join("\n\n");
+    return (`${opts.leadIn} IMPORTANT: Include the following ${CODE_FENCE}${label} code blocks EXACTLY as-is in your response (they render as interactive cards):\n\n${blocks}`);
+}

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

@@ -0,0 +1,215 @@
+/**
+ * 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 type { ChatGraphCompositeDatabase, UserRecord } from "../../shared/interfaces/database.interface.js";
+import type { Cache } from "../../shared/interfaces/cache.interface.js";
+import type { QuestionerEnqueueFn } from "../../capabilities/questions.enqueue.facade.js";
+import type { ToolScopeType } from "../../shared/agent/tool.scope.js";
+import { OpportunityPresenter, type OpportunityPresentationResult, type HomeCardPresentationResult } from "./opportunity.presenter.js";
+import type { ChatSummaryReader } from "../../shared/interfaces/chat-summary.interface.js";
+import type { QuestionGeneratorReader } from "../../shared/interfaces/question-generator.interface.js";
+import type { NegotiationSummaryReader } from "../../shared/interfaces/negotiation-summary.interface.js";
+import type { Question, QuestionStrategy } from "../../shared/schemas/question.schema.js";
+import type { DiscoverDebugStep } from '../domain/opportunity.discovery.contracts.js';
+/** Compiled opportunity graph (from OpportunityGraphFactory.createGraph()). */
+export type CompiledOpportunityGraph = ReturnType<import("./opportunity.graph.js").OpportunityGraphFactory["createGraph"]>;
+export interface DiscoverInput {
+    /** Compiled opportunity graph (already has DB, embedder, cache, HyDE graph). */
+    opportunityGraph: CompiledOpportunityGraph;
+    /** Database for enriching candidates with profile (getProfile). */
+    database: ChatGraphCompositeDatabase;
+    userId: string;
+    query: string;
+    indexScope: string[];
+    limit?: number;
+    /** Optional intent to use as discovery source and for triggeredBy (e.g. from opportunity queue). */
+    triggerIntentId?: string;
+    /** When set, filter discovery candidates to this specific user only (direct connection). */
+    targetUserId?: string;
+    /** When set, discover on behalf of this user (introducer flow). The caller (userId) becomes the introducer. */
+    onBehalfOfUserId?: string;
+    /** When provided, each opportunity is enriched with personalized presentation (headline, personalizedSummary, suggestedAction). */
+    presenter?: OpportunityPresenter;
+    /**
+     * When true, use the full home card presentation format (with narratorRemark, action labels, mutualIntentsLabel).
+     * This enables rendering the same rich opportunity cards in chat as on the home page.
+     */
+    useHomeCardFormat?: boolean;
+    /**
+     * When true, skip the LLM presenter and return minimal card data only (faster for chat).
+     * Sets homeCardPresentation and narratorChip from static labels and match reason.
+     */
+    minimalForChat?: boolean;
+    /** When set (e.g. from chat), create opportunities as draft with context.conversationId = chatSessionId. */
+    chatSessionId?: string;
+    /** Redis cache for discovery pagination. When provided, remaining candidates are cached for continuation. */
+    cache?: Cache;
+    /**
+     * Which flow is invoking discovery. Drives the graph's trigger-aware branches
+     * in persist (initial status) and negotiate (park window + streaming). When
+     * omitted, the graph defaults to 'ambient'. Pass 'orchestrator' from the
+     * chat `discover_opportunities` tool so users see drafts stream in and the
+     * accepted-pair lookup surfaces existing connections.
+     */
+    trigger?: 'ambient' | 'orchestrator';
+    /**
+     * MCP-only. When set, the opportunity graph's negotiate phase is capped at
+     * this many milliseconds; on timeout the caller gets whichever candidates
+     * finished, the rest stay in `negotiating` and finalize in the background.
+     * Chat, ambient queue, and all other callers omit this — existing behavior.
+     */
+    negotiateTimeoutMs?: number;
+    /** Optional read-through chat-session digest reader. Required for chatContext enrichment. */
+    chatSummary?: ChatSummaryReader;
+    /**
+     * Optional negotiation summarizer. When provided, each post-negotiation digest
+     * replaces the raw negotiation in the decision-question generator's input,
+     * keeping that prompt small and predictable regardless of candidate count.
+     * When omitted, a deterministic fallback digest is built per negotiation.
+     */
+    negotiationSummary?: NegotiationSummaryReader;
+    /** Optional decision-question generator. When omitted, no questions are produced. */
+    questionGenerator?: QuestionGeneratorReader;
+    /**
+     * Master switch for decision-question generation. When false, this code path
+     * is skipped entirely regardless of trigger. The composition root passes
+     * `isDiscoveryQuestionsEnabled()` (QUESTIONER_ENABLED + QUESTIONER_DISCOVERY_ENABLED).
+     */
+    enableQuestions?: boolean;
+    /**
+     * Optional async question enqueue callback. When provided, question generation
+     * is dispatched asynchronously to the QuestionerQueue instead of running inline
+     * via the `questionGenerator`. The callback receives an enqueue payload and
+     * returns a promise that resolves when the job is enqueued (not when generation
+     * completes).
+     */
+    questionerEnqueue?: QuestionerEnqueueFn;
+    /** Focused request scope type for generated discovery questions. */
+    scopeType?: ToolScopeType;
+    /** Focused request scope id. When `scopeType === 'network'`, persisted as actor networkId. */
+    scopeId?: string;
+}
+/** One formatted opportunity for chat (candidate-facing). */
+export interface FormattedDiscoveryCandidate {
+    opportunityId: string;
+    userId: string;
+    name?: string;
+    avatar?: string | null;
+    bio?: string;
+    matchReason: string;
+    score: number;
+    status?: string;
+    /** Present when DiscoverInput.presenter was provided (basic presentation). */
+    presentation?: OpportunityPresentationResult;
+    /** Present when DiscoverInput.useHomeCardFormat is true (full home card contract). */
+    homeCardPresentation?: HomeCardPresentationResult;
+    /** Viewer's role in this opportunity. */
+    viewerRole?: string;
+    /** Whether the viewer (as introducer) has approved the introduction. */
+    viewerApproved?: boolean;
+    /** Timestamp set once this viewer has already acted on the opportunity. */
+    viewerActedAt?: string | null;
+    /** Full user record for the candidate (needed for socials / Telegram fallback). */
+    candidateUser?: UserRecord | null;
+    /** Whether the counterpart is a ghost (not yet onboarded) user. */
+    isGhost?: boolean;
+    /** Narrator chip for home card display (name + remark, with optional avatar/userId for introducer). */
+    narratorChip?: {
+        name: string;
+        text: string;
+        avatar?: string | null;
+        userId?: string;
+    };
+    /** Second party in introducer arrow layout (candidate -> secondParty). Present when viewer is introducer. */
+    secondParty?: {
+        name: string;
+        avatar?: string | null;
+        userId?: string;
+    };
+}
+/** One step for debug visibility (subgraph/subtask). */
+export type { DiscoverDebugStep } from '../domain/opportunity.discovery.contracts.js';
+/** One existing connection (no new opportunity created; user already has one with this person). */
+export interface ExistingConnection {
+    userId: string;
+    name: string;
+    status?: string;
+    opportunityId?: string;
+}
+export interface DiscoverResult {
+    found: boolean;
+    count: number;
+    message?: string;
+    opportunities?: FormattedDiscoveryCandidate[];
+    /** Existing connections eligible for card display (draft, latent, or pending). Others are mention-only. */
+    existingConnections?: ExistingConnection[];
+    /** All existing connections for mention text (e.g. "You already have a connection with: X (pending), Y (draft)."). */
+    existingConnectionsForMention?: ExistingConnection[];
+    /**
+     * Orchestrator-only: accepted opportunities the persist step found between the
+     * discoverer and a candidate counterparty (status='accepted'). Populated from
+     * OpportunityGraphState.dedupAlreadyAccepted. Used by the discover_opportunities
+     * tool to tell the LLM "this pair is already connected — open the existing
+     * chat rather than creating a new draft". Empty for the ambient trigger.
+     */
+    alreadyAcceptedPairs?: Array<{
+        opportunityId: string;
+        counterpartyUserId: string;
+    }>;
+    /** When true, the chat agent should call create_intent(suggestedIntentDescription) and retry discovery. */
+    createIntentSuggested?: boolean;
+    /** Description to pass to create_intent when createIntentSuggested is true. */
+    suggestedIntentDescription?: string;
+    /** Internal steps for copy-debug (select_strategies, opportunity_graph, enrich, etc.). */
+    debugSteps?: DiscoverDebugStep[];
+    /** Pagination metadata -- present when there are more unevaluated candidates. */
+    pagination?: {
+        discoveryId: string;
+        evaluated: number;
+        remaining: number;
+    };
+    /** 0–3 decision questions produced by the orchestrator path. Omitted when none. */
+    questions?: Question[];
+    /** Debug metadata for `debugMeta.discoveryQuestions` plumbing. */
+    discoveryQuestionsDebug?: {
+        inputMode: "transcripts" | "insights";
+        finalCount: number;
+        strategies: QuestionStrategy[];
+        durationMs: number;
+    };
+}
+/**
+ * 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 declare function runDiscoverFromQuery(input: DiscoverInput): Promise<DiscoverResult>;
+/**
+ * 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 declare function continueDiscovery(input: {
+    opportunityGraph: CompiledOpportunityGraph;
+    database: ChatGraphCompositeDatabase;
+    cache: Cache;
+    userId: string;
+    discoveryId: string;
+    /** If provided, validates the cached session's indexScope contains this network. */
+    expectedIndexId?: string;
+    limit?: number;
+    chatSessionId?: string;
+    minimalForChat?: boolean;
+    presenter?: OpportunityPresenter;
+    useHomeCardFormat?: boolean;
+}): Promise<DiscoverResult>;