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

package/dist/opportunity/application/opportunity.presenter.js

@@ -0,0 +1,736 @@
+/**
+ * Opportunity Presenter Agent
+ *
+ * Generates personalized, second-person explanations of why an opportunity
+ * matters to the viewing user. Uses full opportunity data (interpretation,
+ * actors, profiles, intents, index) to produce headline, personalizedSummary,
+ * and suggestedAction for chat tools and user-facing surfaces.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { z } from "zod";
+import { Timed } from "../../shared/observability/performance.js";
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+import { createStructuredModel } from "../../shared/agent/model.config.js";
+import { viewerCentricCardSummary } from "../domain/opportunity.presentation.js";
+import { stripUuids, stripIntroducerMentions } from "../domain/opportunity.presentation.js";
+import { stripUnsupportedOpportunityClaims } from "../domain/opportunity.claim-safety.js";
+import { DEFAULT_EMPTY_FALLBACK_TEXT, DEFAULT_FALLBACK_ACTION, DEFAULT_FALLBACK_HEADLINE, safeFallbackSummary } from "../domain/opportunity.safe-presentation.js";
+const presentLog = protocolLogger("OpportunityPresenter:present");
+const presentHomeCardLog = protocolLogger("OpportunityPresenter:presentHomeCard");
+const LLM_TIMEOUT_MS = 20000;
+const GREETING_DESCRIPTION = "A 2-4 sentence first-person message the viewer could send to the counterpart, in the viewer's voice, referencing what they have in common. Plain prose only — no markdown, no greeting prefix like 'Hey {Name},'. Example body: 'Saw we're both working on regenerative coordination tooling — your post on consent flows resonated. Would love to compare notes if you have time this week.'";
+// ──────────────────────────────────────────────────────────────
+// SCHEMA & TYPES
+// ──────────────────────────────────────────────────────────────
+const PresentationSchema = z.object({
+    headline: z
+        .string()
+        .describe("Short, compelling headline for this opportunity (e.g., 'A React expert who needs your design skills')"),
+    personalizedSummary: z
+        .string()
+        .describe("2-3 sentence explanation using 'you' language, explaining why this opportunity is specifically valuable for the viewer based on their intents and profile"),
+    suggestedAction: z.string().describe("Brief suggested next step"),
+    greeting: z.string().max(500).describe(GREETING_DESCRIPTION),
+});
+const responseFormat = z.object({
+    presentation: PresentationSchema,
+});
+/** LLM-generated fields for home-card presentation (buttons are hardcoded by callers, not LLM-generated). */
+export const HomeCardLLMSchema = z.object({
+    headline: z
+        .string()
+        .describe("Short, compelling headline for this opportunity"),
+    personalizedSummary: z
+        .string()
+        .describe("2-3 sentence explanation in 'you' language for the main card body"),
+    digestSummary: z
+        .string()
+        .max(220)
+        .describe("One concise digest-ready sentence for a morning brief. It must be addressed to the viewer and mention the counterpart by name, e.g. 'You might like meeting Paul because ...'. No markdown."),
+    suggestedAction: z
+        .string()
+        .describe("Brief suggested next step (e.g. CTA line)"),
+    narratorRemark: z
+        .string()
+        .max(80)
+        .describe("One short sentence for the narrator chip, max ~80 chars (e.g. who is suggesting and why)"),
+    mutualIntentsLabel: z
+        .string()
+        .max(48)
+        .describe("Short line for the subtitle under the other party name (e.g. '3 mutual intents', 'Shared interests', 'Aligned goals'). NEVER output '0 mutual intents' — use a qualitative phrase like 'Shared interests' when no numeric count is available."),
+    greeting: z.string().max(500).describe(GREETING_DESCRIPTION),
+});
+const homeCardResponseFormat = z.object({
+    presentation: HomeCardLLMSchema,
+});
+// ──────────────────────────────────────────────────────────────
+// SYSTEM PROMPT
+// ──────────────────────────────────────────────────────────────
+const systemPrompt = `
+You are an expert at presenting connection opportunities to users in a way that feels personal and compelling.
+
+Your goal: Given raw context about the viewer (their profile, intents), the other person(s), and why the system matched them, produce a short headline, a personalized summary, and a suggested action.
+
+Rules:
+1. Address the VIEWER directly using "you" and "your". This is for them.
+2. Be concise and compelling — not analytical or third-party. No "The source user" or "The candidate"; use names or "they" where needed.
+3. Do not leak private or confidential details. Use only the context provided.
+4. Vary user-facing nouns naturally. Do not repeatedly use the same label in one response.
+5. If possible, avoid repeating "opportunity" in both headline and summary. Prefer alternatives like "connection", "thought partner", "mutual fit", "valuable conversation", or "peer".
+6. Prefer first names in user-facing copy. Do not repeatedly use full names unless needed to disambiguate.
+7. Network assignment, network title/type, and network/event metadata are retrieval context only. They are NEVER proof that a person attended or will attend, belongs to a group, resides in a place, knows anyone from the network, or shared a session, time, place, or location with anyone. Do not make co-attendance, membership, residence, shared-session, or same-place/same-time claims from network co-membership.
+
+**Introduction-originated opportunities:**
+When INTRODUCTION CONTEXT is provided, this opportunity was explicitly created by an introducer (a real person who saw value in this connection). This is NOT an automatic system discovery — someone made a deliberate judgment.
+- For ALL roles: acknowledge the introducer's role naturally. E.g., "[Introducer name] thinks you should meet [other person]" or "[Introducer name] connected you because..."
+- The introduction itself is a strong signal — treat it with the weight of a personal recommendation.
+- If the parties' intents don't obviously overlap, that's fine — the introducer saw something worth connecting. Focus on what the introducer likely saw.
+
+**Role-Specific Presentation:**
+
+**If viewer is "introducer":**
+- The viewer suggested this connection between two (or more) OTHER people. The opportunity is NOT about the viewer's own needs.
+- Headline: describe the connection between the parties (e.g., "Connecting a React expert with a startup founder").
+- Personalized summary: explain why the people YOU are introducing should meet. Reference THEIR profiles and intents, not yours. Frame it as "you're connecting X and Y because..." rather than "this matches your intent".
+- Suggested action: guide sharing (e.g., "Share this with [name] to get things started").
+- CRITICAL: Do NOT reference the introducer's own intents, skills, or needs. The introducer is the matchmaker, not a party.
+
+**If viewer is "patient" or "party":**
+- Reference their specific intents, skills, or interests that align with this opportunity.
+- If this is an introduction: mention who introduced them and frame it as a personal recommendation.
+- Headline: one short line that hooks (e.g., "[Name] thinks you should meet [Other]" or "A React expert who needs your design skills").
+- Personalized summary: 2-3 sentences. Why is this opportunity for *them*? If introduced, lead with the introduction.
+- Suggested action: encourage action ("Send a message to start the conversation" or "Share this intro").
+
+**If viewer is "agent":**
+- They are seeing this because someone already reached out.
+- If this is an introduction: mention who made the introduction.
+- Reference their skills/expertise that make them a match.
+- Headline: what the other person needs that they can provide.
+- Personalized summary: 2-3 sentences. Why someone reached out to them.
+- Suggested action: "Someone is interested in connecting — check their message" or "Review and respond".
+
+**If viewer is "peer":**
+- Mutual opportunity. Reference shared or complementary interests.
+- If this is an introduction: mention who connected them.
+- Headline: the mutual connection angle.
+- Personalized summary: 2-3 sentences. Why this is mutually valuable.
+- Suggested action: "Send an intro to connect" or "Start a conversation".
+`;
+const homeCardSystemPrompt = `
+You are an expert at presenting connection opportunities for a home feed card.
+
+Given context about the viewer, the other person, and why they were matched, produce:
+1. headline: one short hook line.
+2. personalizedSummary: 2-3 sentences in "you" language (main body text).
+3. digestSummary: one polished morning-brief sentence that can be printed directly after the person's linked name. No markdown, no field labels.
+4. suggestedAction: one brief suggested next step.
+5. narratorRemark: one short sentence for the narrator chip (who is suggesting and why; max ~80 chars).
+6. greeting: a 2-4 sentence first-person message the viewer could send to the counterpart. Plain prose, no greeting prefix, no markdown.
+7. mutualIntentsLabel: short subtitle under the other party's name. Examples: "3 mutual intents", "Shared interests", "Aligned goals" — keep it brief. NEVER output "0 mutual intents" or any zero-count label; use a qualitative phrase instead.
+
+Rules:
+- Address the viewer with "you"/"your". Be concise and compelling.
+- narratorRemark should feel like a single sentence from the narrator (Index or a person), not meta-commentary.
+- narratorRemark is displayed with the narrator name prepended (e.g. "Index: …" or "Alice: …"). Do NOT start narratorRemark with the narrator's name or repeat it; write only the remark (e.g. "Based on your overlapping intents" or "introduced you two, sensing a valuable connection").
+- Vary wording for the match itself. Do not repeat "opportunity" across headline, summary, and narratorRemark when alternatives fit.
+- Prefer first names in user-facing copy. Avoid repeated full names unless disambiguation is necessary.
+- Network assignment, network title/type, and network/event metadata are retrieval context only. They are NEVER proof that a person attended or will attend, belongs to a group, resides in a place, knows anyone from the network, or shared a session, time, place, or location with anyone. Do not make co-attendance, membership, residence, shared-session, or same-place/same-time claims from network co-membership.
+- digestSummary must be grammatically complete as a standalone sentence. It should usually start with "You might like meeting {Name} because ..." for direct connections, or "You may be able to help {Name} because ..." for connector/introducer cards.
+- digestSummary must NOT use awkward third-person fragments like "Name is...", "they're ..., and is...", "you is...", or "the discoverer's query".
+- digestSummary must be one sentence, MUST fit within 180 characters when possible, and MUST contain no markdown links; the caller will attach links.
+- If you cannot fit every detail, choose one clear reason and stop. Do not rely on downstream truncation.
+
+**Introduction-originated opportunities (ONLY when INTRODUCTION CONTEXT is provided):**
+When INTRODUCTION CONTEXT is provided, this opportunity was explicitly created by an introducer. It was NOT automatically discovered.
+- For parties/patients/agents/peers viewing an introduction: keep the introducer signal in narratorRemark (and narrator chip), not in personalizedSummary.
+- For these introduced parties, personalizedSummary must focus ONLY on fit/value between viewer and counterpart. Do NOT mention the introducer there.
+- narratorRemark should carry the introduction signal (e.g., "saw strong alignment between you two" or "thought this connection could be valuable"), without repeating the narrator name at the start.
+- This is a personal recommendation, not an algorithm match. Frame it accordingly.
+
+**CRITICAL: NEVER include introducer names in personalizedSummary. Examples:**
+❌ WRONG: "Seref introduced you to Lucy, who is actively seeking a product co-founder..."
+✅ CORRECT: "Lucy is actively seeking a product co-founder for a niche APAC marketplace. With your expertise in UX and AI, this could be an ideal collaboration."
+
+❌ WRONG: "Bob thinks you should meet Alice because your React skills align with her needs."
+✅ CORRECT: "Alice is building a React-based platform and needs frontend expertise. Your experience with component architecture makes you a strong fit."
+
+❌ WRONG: "Jane connected you to Mark, who is looking for a designer."
+✅ CORRECT: "Mark is building a consumer app and needs design expertise. Your background in user-centered design aligns well with what he's building."
+
+Remember: The introducer's name goes ONLY in narratorRemark, NEVER in personalizedSummary.
+
+**When INTRODUCTION CONTEXT is NOT provided (system-discovered match):**
+- Do NOT use introducer-style wording. Do NOT say "you suggested", "this is an introduction you suggested", or "you suggested this connection". The system found this match; no human introducer was involved.
+- Instead, narratorRemark should describe why the match is relevant (e.g. "Based on your overlapping intents", "Your skills align with what they need").
+
+**Negotiation-grounded explanations (ONLY when NEGOTIATION CONTEXT is provided):**
+When NEGOTIATION CONTEXT is provided, this opportunity passed through an agent-to-agent negotiation. Use the transcript to ground your explanation in the concrete reasoning the agents exchanged.
+- Personalize the summary with *why* the negotiation produced this match — reference the roles the agents agreed on, the specific concerns raised, and how they were resolved.
+- For status "stalled" with reason "turn_cap": the agents hit the turn limit without reaching agreement. Frame the card as a hedged possibility rather than a confident match; narratorRemark should signal "agents couldn't fully converge" without sounding negative.
+- For status "stalled" with reason "timeout": one side went silent. Suggest the user re-engage if interested.
+- For status "accepted": the agents agreed; the card should confidently explain *why* they agreed.
+- For status "rejected": the agents declined. The card should explain the reason briefly so the user understands — not dwell on it.
+- Do NOT invent turn content. Only reference what is in the NEGOTIATION CONTEXT block.
+
+- Exception for connector/introducer: if viewer role is "introducer" (any status), this is a curation/connector card. Use:
+  - suggestedAction: one short line about sharing the intro or confirming the match.
+  - mutualIntentsLabel: a short connector label (e.g. "Connector match", "You can bridge this").
+  - headline: describe the connection between the parties (e.g., "Connecting a PhD researcher with a translator"). Do NOT reference the introducer's own needs.
+  - personalizedSummary: explain why the parties you're introducing should meet, referencing THEIR profiles and intents, not yours.
+
+**CRITICAL for latent introducer cards (opportunity status is "latent"):**
+When the viewer is the introducer and the opportunity status is "latent", the introducer has NOT yet approved this match. They are evaluating whether to make the introduction.
+- narratorRemark MUST use evaluation/curation language (e.g. "Could be a strong match", "Worth introducing?", "Interesting overlap here").
+- Do NOT say "you suggested", "you introduced", "you connected", or any past-tense language implying the introduction was already made.
+- suggestedAction should encourage evaluation (e.g. "Approve if you see the fit").
+- Exception for new-connection reveal: if viewer role is "agent", status is "accepted", and there is an introducer, this is the agent's first time seeing this opportunity. Use:
+  - suggestedAction: a short line about joining the conversation.
+`;
+// ──────────────────────────────────────────────────────────────
+// DETERMINISTIC OUTPUT VALIDATION
+// ──────────────────────────────────────────────────────────────
+function sanitizePresenterField(value, fallback, allowEmpty = fallback === "") {
+    const cleaned = stripUnsupportedOpportunityClaims(stripUuids(value));
+    if (cleaned || allowEmpty) {
+        return { value: cleaned, usedFallback: false };
+    }
+    return { value: fallback, usedFallback: true };
+}
+// ──────────────────────────────────────────────────────────────
+// CLASS
+// ──────────────────────────────────────────────────────────────
+export class OpportunityPresenter {
+    constructor() {
+        this.model = createStructuredModel("opportunityPresenter", responseFormat, {
+            name: "opportunity_presenter",
+        });
+        this.homeCardModel = createStructuredModel("opportunityPresenter", homeCardResponseFormat, {
+            name: "opportunity_presenter_home_card",
+        });
+    }
+    async invokeWithTimeout(targetModel, messages, signal) {
+        const timeoutReason = `LLM invoke timed out after ${LLM_TIMEOUT_MS}ms`;
+        const controller = new AbortController();
+        let timeoutId;
+        const combinedSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+        const invokePromise = targetModel.invoke(messages, { signal: combinedSignal });
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                controller.abort(timeoutReason);
+                reject(new Error(timeoutReason));
+            }, LLM_TIMEOUT_MS);
+        });
+        try {
+            return await Promise.race([invokePromise, timeoutPromise]);
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    /**
+     * Generate personalized presentation for a single opportunity.
+     */
+    async present(input, options = {}) {
+        const introContext = input.isIntroduction
+            ? `\nINTRODUCTION CONTEXT: This opportunity was created by an explicit introduction from ${input.introducerName ?? "someone in the community"}. It was NOT discovered automatically — a real person made this connection.\n`
+            : "";
+        const humanContent = `
+VIEWER (the person seeing this opportunity):
+${input.viewerContext}
+
+OTHER PARTY:
+${input.otherPartyContext}
+
+MATCH CONTEXT:
+- Category: ${input.category}
+- Confidence: ${input.confidence}
+- Why we matched: ${input.matchReasoning}
+- Signals: ${input.signalsSummary}
+${introContext}
+COMMUNITY: ${input.indexName}
+Viewer's role in this opportunity: ${input.viewerRole}
+
+Produce headline, personalizedSummary (2-3 sentences in "you" language), suggestedAction, and greeting.
+`;
+        try {
+            const messages = [
+                new SystemMessage(systemPrompt),
+                new HumanMessage(humanContent),
+            ];
+            const result = await this.invokeWithTimeout(this.model, messages, options.signal);
+            const parsed = responseFormat.parse(result);
+            const headline = sanitizePresenterField(parsed.presentation.headline, DEFAULT_FALLBACK_HEADLINE);
+            const summary = sanitizePresenterField(parsed.presentation.personalizedSummary, DEFAULT_EMPTY_FALLBACK_TEXT);
+            const action = sanitizePresenterField(parsed.presentation.suggestedAction, DEFAULT_FALLBACK_ACTION);
+            const greeting = sanitizePresenterField(parsed.presentation.greeting, "");
+            const usedFallback = headline.usedFallback || summary.usedFallback || action.usedFallback || greeting.usedFallback;
+            return {
+                headline: headline.value,
+                personalizedSummary: summary.value,
+                suggestedAction: action.value,
+                greeting: greeting.value,
+                ...(usedFallback ? { isFallback: true, fallbackReason: "sanitization" } : {}),
+            };
+        }
+        catch (e) {
+            if (options.signal?.aborted)
+                throw e;
+            const message = e instanceof Error ? e.message : String(e);
+            const timeoutReason = message.includes("timed out") ? message : undefined;
+            presentLog.warn("LLM failed, returning fallback", {
+                event: "presenter_fallback",
+                presenter: "opportunity",
+                reason: timeoutReason ? "timeout" : "parse_error",
+                message,
+                timeoutReason,
+            });
+            return {
+                headline: DEFAULT_FALLBACK_HEADLINE,
+                personalizedSummary: safeFallbackSummary(input.matchReasoning),
+                suggestedAction: DEFAULT_FALLBACK_ACTION,
+                greeting: "",
+                isFallback: true,
+                fallbackReason: timeoutReason ? "timeout" : "error",
+            };
+        }
+    }
+    /**
+     * Generate LLM-powered home-card content (headline, body, narrator remark, mutual-intent label).
+     * Callers append button labels from opportunity.constants.
+     *
+     * When `negotiationContext.status === 'negotiating'`, returns a templated
+     * chip synchronously without invoking the LLM — the card just reflects
+     * "negotiation in progress" at that point.
+     */
+    async presentHomeCard(input) {
+        if (input.negotiationContext?.status === 'negotiating') {
+            return buildNegotiatingChip(input);
+        }
+        const mutualHint = input.mutualIntentCount != null && input.mutualIntentCount > 0
+            ? `There are ${input.mutualIntentCount} overlapping intent(s) between viewer and other party.`
+            : "Match is based on profile and intent alignment. Do not cite a numeric intent count.";
+        const introContext = input.isIntroduction
+            ? `\nINTRODUCTION CONTEXT: This opportunity was created by an explicit introduction from ${input.introducerName ?? "someone in the community"}. It was NOT discovered automatically — a real person made this connection.\n`
+            : "";
+        const negotiationBlock = buildNegotiationPromptBlock(input.negotiationContext);
+        // When negotiation context exists, lead with it — these cards exist
+        // *because* the negotiation happened. Trailing the block lets weaker
+        // models lean on surface signals and ignore the transcript entirely.
+        const negotiationDirective = negotiationBlock
+            ? `\nIMPORTANT: This opportunity surfaced because the agents negotiated and converged. Both your personalizedSummary AND your digestSummary MUST reference at least one specific signal from the NEGOTIATION CONTEXT block below — what concern was raised, what was confirmed, what the agents agreed on. The digestSummary is the one-line morning-brief sentence a user reads before deciding to act, so it must communicate *why this specific match* surfaced now (the negotiation that led to it), not a generic skill-complementarity line. Do not produce the generic summary every card looked like before this negotiation happened.\n`
+            : "";
+        const humanContent = `
+${negotiationBlock}${negotiationDirective}
+VIEWER (the person seeing this opportunity):
+${input.viewerContext}
+
+OTHER PARTY:
+${input.otherPartyContext}
+
+MATCH CONTEXT:
+- Category: ${input.category}
+- Confidence: ${input.confidence}
+- Why we matched: ${input.matchReasoning}
+- Signals: ${input.signalsSummary}
+- ${mutualHint}
+${introContext}
+COMMUNITY: ${input.indexName}
+Viewer's role in this opportunity: ${input.viewerRole}
+Opportunity status: ${input.opportunityStatus ?? "pending"}
+
+Produce headline, personalizedSummary, digestSummary, suggestedAction, narratorRemark, greeting, and mutualIntentsLabel.
+`;
+        const isIntroducer = input.viewerRole === "introducer";
+        try {
+            const messages = [
+                new SystemMessage(homeCardSystemPrompt),
+                new HumanMessage(humanContent),
+            ];
+            const result = await this.invokeWithTimeout(this.homeCardModel, messages);
+            const parsed = homeCardResponseFormat.parse(result);
+            if (/^0\s+(mutual|overlapping)\s+intent/i.test(parsed.presentation.mutualIntentsLabel)) {
+                parsed.presentation.mutualIntentsLabel = "Shared interests";
+            }
+            if (input.isIntroduction && input.introducerName) {
+                parsed.presentation.personalizedSummary = stripIntroducerMentions(parsed.presentation.personalizedSummary, input.introducerName);
+                parsed.presentation.digestSummary = stripIntroducerMentions(parsed.presentation.digestSummary, input.introducerName);
+            }
+            const fields = {
+                headline: sanitizePresenterField(parsed.presentation.headline, DEFAULT_FALLBACK_HEADLINE),
+                personalizedSummary: sanitizePresenterField(parsed.presentation.personalizedSummary, DEFAULT_EMPTY_FALLBACK_TEXT),
+                digestSummary: sanitizePresenterField(parsed.presentation.digestSummary, isIntroducer
+                    ? "You may be able to help make a useful introduction here."
+                    : "You might like meeting them based on your current interests."),
+                suggestedAction: sanitizePresenterField(parsed.presentation.suggestedAction, DEFAULT_FALLBACK_ACTION),
+                narratorRemark: sanitizePresenterField(parsed.presentation.narratorRemark, "Worth a look."),
+                mutualIntentsLabel: sanitizePresenterField(parsed.presentation.mutualIntentsLabel, isIntroducer ? "Connector match" : "Shared interests"),
+                greeting: sanitizePresenterField(parsed.presentation.greeting, ""),
+            };
+            const usedFallback = Object.values(fields).some((field) => field.usedFallback);
+            return {
+                headline: fields.headline.value,
+                personalizedSummary: fields.personalizedSummary.value,
+                digestSummary: fields.digestSummary.value,
+                suggestedAction: fields.suggestedAction.value,
+                narratorRemark: fields.narratorRemark.value,
+                mutualIntentsLabel: fields.mutualIntentsLabel.value,
+                greeting: fields.greeting.value,
+                ...(usedFallback ? { isFallback: true } : {}),
+            };
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            const timeoutReason = message.includes("timed out") ? message : undefined;
+            presentHomeCardLog.warn("LLM failed, returning fallback", {
+                event: "presenter_fallback",
+                presenter: "home_card",
+                reason: timeoutReason ? "timeout" : "parse_error",
+                message,
+                timeoutReason,
+            });
+            const fallbackSummary = safeFallbackSummary(input.matchReasoning, {
+                introducerName: input.isIntroduction ? input.introducerName : undefined,
+            });
+            return {
+                headline: "A promising connection",
+                personalizedSummary: fallbackSummary,
+                digestSummary: isIntroducer
+                    ? "You may be able to help make a useful introduction here."
+                    : "You might like meeting them based on your current interests.",
+                suggestedAction: isIntroducer
+                    ? "Share this introduction to get things started."
+                    : "Take a look and decide whether to reach out.",
+                narratorRemark: "Worth a look.",
+                mutualIntentsLabel: isIntroducer
+                    ? "Connector match"
+                    : input.mutualIntentCount != null && input.mutualIntentCount > 0
+                        ? `${input.mutualIntentCount} mutual intent${input.mutualIntentCount !== 1 ? "s" : ""}`
+                        : "Shared interests",
+                greeting: "",
+                isFallback: true,
+            };
+        }
+    }
+    /**
+     * Process multiple opportunities in parallel with bounded concurrency.
+     */
+    async presentBatch(inputs, options) {
+        const concurrency = options?.concurrency ?? 5;
+        const results = [];
+        for (let i = 0; i < inputs.length; i += concurrency) {
+            const chunk = inputs.slice(i, i + concurrency);
+            const chunkResults = await Promise.all(chunk.map((inp) => this.present(inp)));
+            results.push(...chunkResults);
+        }
+        return results;
+    }
+    /**
+     * Process multiple opportunities as home cards in parallel with bounded concurrency.
+     * Returns full home-card display contracts (headline, body, narrator remark, action labels, mutual-intent label).
+     */
+    async presentHomeCardBatch(inputs, options) {
+        const concurrency = options?.concurrency ?? 5;
+        const results = [];
+        for (let i = 0; i < inputs.length; i += concurrency) {
+            const chunk = inputs.slice(i, i + concurrency);
+            const chunkResults = await Promise.all(chunk.map((inp) => this.presentHomeCard(inp)));
+            results.push(...chunkResults);
+        }
+        return results;
+    }
+}
+__decorate([
+    Timed(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], OpportunityPresenter.prototype, "present", null);
+__decorate([
+    Timed(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], OpportunityPresenter.prototype, "presentHomeCard", null);
+__decorate([
+    Timed(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array, Object]),
+    __metadata("design:returntype", Promise)
+], OpportunityPresenter.prototype, "presentBatch", null);
+__decorate([
+    Timed(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array, Object]),
+    __metadata("design:returntype", Promise)
+], OpportunityPresenter.prototype, "presentHomeCardBatch", null);
+// ──────────────────────────────────────────────────────────────
+// NEGOTIATION CONTEXT HELPERS
+// ──────────────────────────────────────────────────────────────
+/**
+ * Builds a "NEGOTIATION CONTEXT:" block for the home-card prompt. Returns an
+ * empty string when the opportunity has no meaningful negotiation context
+ * (draft/latent) or when the opportunity is still negotiating (handled via
+ * the templated chip, not the LLM).
+ */
+function buildNegotiationPromptBlock(context) {
+    if (!context || context.status === 'negotiating')
+        return "";
+    const turnCapLabel = context.turnCap > 0 ? `${context.turnCap}` : "unlimited";
+    const reason = context.outcome?.reason;
+    const reasonLabel = reason === 'turn_cap'
+        ? "agents hit the turn cap without converging"
+        : reason === 'timeout'
+            ? "counterpart went silent before responding"
+            : undefined;
+    const turnLines = (context.turns ?? []).map((turn, index) => {
+        const action = turn.action;
+        const reasoning = turn.assessment?.reasoning ?? "(no reasoning)";
+        const message = turn.message ? ` — said: "${turn.message}"` : "";
+        return `Turn ${index + 1} (${action}): ${reasoning}${message}`;
+    });
+    const outcomeSummary = context.outcome
+        ? `Final outcome: ${context.outcome.hasOpportunity ? "agreed" : "declined"} — ${context.outcome.reasoning}`
+        : "Final outcome: not recorded.";
+    return `
+NEGOTIATION CONTEXT:
+- Negotiation status: ${context.status}${reasonLabel ? ` (${reasonLabel})` : ""}
+- Turns exchanged: ${context.turnCount} of ${turnCapLabel}
+- Transcript:
+${turnLines.length > 0 ? turnLines.map((l) => `  ${l}`).join("\n") : "  (no turns recorded)"}
+- ${outcomeSummary}
+`;
+}
+/**
+ * Builds a templated home-card result for an opportunity whose negotiation
+ * is still in progress. Bypasses the LLM so users see a stable "currently
+ * negotiating" chip while turns are still being exchanged.
+ */
+function buildNegotiatingChip(input) {
+    const ctx = input.negotiationContext;
+    const turnCount = ctx?.turnCount ?? 0;
+    const turnCap = ctx?.turnCap && ctx.turnCap > 0 ? ctx.turnCap : undefined;
+    const narratorRemark = turnCap
+        ? `Currently negotiating · turn ${turnCount} of ${turnCap}`
+        : `Currently negotiating · turn ${turnCount}`;
+    return {
+        headline: "Negotiation in progress",
+        personalizedSummary: "Your agent is still talking with theirs to see if this connection makes sense. We'll surface the full match as soon as they converge.",
+        digestSummary: "Your agent is still checking whether this connection makes sense.",
+        suggestedAction: "Check back shortly — no action needed yet.",
+        narratorRemark,
+        mutualIntentsLabel: input.mutualIntentCount && input.mutualIntentCount > 0
+            ? `${input.mutualIntentCount} mutual intent${input.mutualIntentCount !== 1 ? "s" : ""}`
+            : "Shared interests",
+        greeting: "",
+    };
+}
+// ──────────────────────────────────────────────────────────────
+// CONTEXT GATHERER (used by tools)
+// ──────────────────────────────────────────────────────────────
+/**
+ * Build the LLM-facing signal summary while excluding pool adjustments. Pool
+ * disposition is rendered deterministically by the card chip; asking the
+ * presenter to interpret it could turn a demotion into a positive rationale.
+ */
+export function summarizeSignalsForPresenter(signals) {
+    const safeSignals = signals?.filter((signal) => signal.type !== 'pool_discriminator') ?? [];
+    if (safeSignals.length === 0)
+        return 'Match based on profile and intent alignment.';
+    return safeSignals.map((signal) => `${signal.type}: ${signal.detail ?? signal.type}`).join('; ');
+}
+/**
+ * Gather all context needed for the presenter from the database.
+ * Fetches viewer profile, viewer intents, other party profile(s), and index in parallel.
+ *
+ * @param displayCounterpartUserId - When set (e.g. for home card), only this counterpart is included in otherPartyContext so the presenter writes about the person on the card. Omitted for introducer view (card shows both parties).
+ */
+export async function gatherPresenterContext(database, opportunity, viewerId, displayCounterpartUserId) {
+    const myActor = opportunity.actors.find((a) => a.userId === viewerId);
+    if (!myActor) {
+        throw new Error("Viewer is not an actor in this opportunity");
+    }
+    const isIntroducer = myActor.role === "introducer";
+    const otherActors = opportunity.actors.filter((a) => a.userId !== viewerId);
+    let otherPartyIds = [...new Set(otherActors.map((a) => a.userId))];
+    if (displayCounterpartUserId &&
+        !isIntroducer &&
+        otherPartyIds.includes(displayCounterpartUserId)) {
+        otherPartyIds = [displayCounterpartUserId];
+    }
+    const contextIndexId = opportunity.context?.networkId;
+    // For introducers: fetch profiles + intents for both parties; skip introducer's own intents.
+    // For other roles: fetch viewer's profile + intents and other party profiles.
+    const [viewerProfile, indexRecord, ...otherProfiles] = await Promise.all([
+        database.getProfile(viewerId),
+        contextIndexId ? database.getNetwork(contextIndexId) : Promise.resolve(null),
+        ...otherPartyIds.map((uid) => database.getProfile(uid)),
+    ]);
+    // Fetch intents: for introducer, fetch each party's intents; otherwise fetch viewer's intents.
+    let viewerIntents;
+    let partyIntentsMap;
+    if (isIntroducer) {
+        const partyIntentResults = await Promise.all(otherPartyIds.map(async (uid) => ({
+            uid,
+            intents: await database.getActiveIntents(uid),
+        })));
+        partyIntentsMap = new Map(partyIntentResults.map((r) => [r.uid, r.intents]));
+    }
+    else {
+        viewerIntents = await database.getActiveIntents(viewerId);
+    }
+    // Fetch premises when any actor is premise-grounded
+    const premiseGroundedActors = opportunity.actors.filter((a) => a.premise);
+    let viewerPremiseContext = '';
+    let otherPremiseContext = '';
+    if (premiseGroundedActors.length > 0) {
+        // Only fetch premises for actors that are actually premise-grounded, not all parties
+        const groundedOtherIds = premiseGroundedActors
+            .filter((a) => a.userId !== viewerId)
+            .map((a) => a.userId);
+        const viewerIsGrounded = premiseGroundedActors.some((a) => a.userId === viewerId);
+        const results = await Promise.all([
+            ...(viewerIsGrounded ? [database.getPremisesForUser(viewerId, 'ACTIVE')] : []),
+            ...groundedOtherIds.map((uid) => database.getPremisesForUser(uid, 'ACTIVE')),
+        ]);
+        let idx = 0;
+        if (viewerIsGrounded) {
+            const viewerPremises = results[idx++];
+            if (viewerPremises?.length) {
+                viewerPremiseContext =
+                    '\nPremises (self-descriptions):\n' +
+                        viewerPremises
+                            .slice(0, 5)
+                            .map((p) => `- ${p.assertion.text}`)
+                            .join('\n');
+            }
+        }
+        const otherPremiseLines = [];
+        for (let i = 0; i < groundedOtherIds.length; i++) {
+            const premises = results[idx++];
+            if (premises?.length) {
+                for (const p of premises.slice(0, 3)) {
+                    otherPremiseLines.push(`- ${p.assertion.text}`);
+                }
+            }
+        }
+        if (otherPremiseLines.length > 0) {
+            otherPremiseContext = '\nPremises (self-descriptions):\n' + otherPremiseLines.join('\n');
+        }
+    }
+    let viewerContext;
+    let otherPartyContext;
+    if (isIntroducer) {
+        // Introducer view: minimal viewer context (just name + role), rich other-party context with intents
+        const introducerApproved = opportunity.actors.find(a => a.role === 'introducer')?.approved === true;
+        const hasApproved = introducerApproved || opportunity.status !== 'latent';
+        viewerContext = [
+            "Profile:",
+            `Name: ${viewerProfile?.identity?.name ?? "Unknown"}`,
+            hasApproved
+                ? "Role: You are the introducer who suggested this connection."
+                : "Role: You are being asked whether these two people would benefit from meeting. You have NOT yet approved this introduction.",
+        ].join("\n");
+        const otherParts = otherPartyIds.map((uid, idx) => {
+            const profile = otherProfiles[idx];
+            const name = profile?.identity?.name ?? "Unknown";
+            const bio = profile?.identity?.bio ?? "";
+            const location = profile?.identity?.location ?? "";
+            const context = profile?.context ?? "";
+            const intents = partyIntentsMap?.get(uid);
+            const intentLines = intents?.length
+                ? intents
+                    .slice(0, 5)
+                    .map((i) => `  - ${i.payload}${i.summary ? ` (${i.summary})` : ""}`)
+                : ["  (no active intents)"];
+            return [
+                `${name}:`,
+                `  Bio: ${bio}`,
+                location ? `  Location: ${location}` : null,
+                context ? `  Context: ${context}` : null,
+                `  Active intents:`,
+                ...intentLines,
+            ]
+                .filter(Boolean)
+                .join("\n");
+        });
+        otherPartyContext =
+            otherParts.join("\n\n") || "Parties (details not available).";
+    }
+    else {
+        // Non-introducer view: full viewer profile + intents, other party profiles
+        const viewerContextLines = [
+            "Profile:",
+            `Name: ${viewerProfile?.identity?.name ?? "Unknown"}`,
+            `Bio: ${viewerProfile?.identity?.bio ?? ""}`,
+            `Location: ${viewerProfile?.identity?.location ?? ""}`,
+            `Context: ${viewerProfile?.context ?? ""}`,
+            "Active intents:",
+            ...(viewerIntents?.length
+                ? viewerIntents.map((i) => `- ${i.payload}${i.summary ? ` (${i.summary})` : ""}`)
+                : ["(none listed)"]),
+        ];
+        viewerContext = viewerContextLines.join("\n");
+        const otherParts = otherPartyIds.map((uid, idx) => {
+            const profile = otherProfiles[idx];
+            const name = profile?.identity?.name ?? "Unknown";
+            const bio = profile?.identity?.bio ?? "";
+            return `${name}: ${bio}`;
+        });
+        otherPartyContext =
+            otherParts.join("\n\n") || "Other party (details not available).";
+    }
+    const interp = opportunity.interpretation;
+    const signalsSummary = summarizeSignalsForPresenter(interp.signals);
+    // Detect introduction-originated opportunities: only when there is an explicit introducer actor.
+    // Do NOT use detection.source === "manual" alone — system-discovered opportunities can have manual source without an introducer.
+    const introducerActor = opportunity.actors.find((a) => a.role === "introducer");
+    const isIntroduction = !!introducerActor;
+    let introducerName;
+    if (introducerActor) {
+        introducerName = opportunity.detection.createdByName;
+        if (!introducerName) {
+            const introducerProfile = await database.getProfile(introducerActor.userId);
+            introducerName = introducerProfile?.identity?.name ?? undefined;
+        }
+    }
+    const counterpartName = otherPartyIds.length === 1 && otherProfiles[0]
+        ? otherProfiles[0]?.identity?.name?.trim()
+        : undefined;
+    const viewerNameForFilter = viewerProfile?.identity?.name?.trim();
+    const matchReasoning = counterpartName && interp.reasoning
+        ? viewerCentricCardSummary(interp.reasoning, counterpartName, 400, viewerNameForFilter, introducerName)
+        : stripUuids(interp.reasoning);
+    if (viewerPremiseContext) {
+        viewerContext += viewerPremiseContext;
+    }
+    if (otherPremiseContext) {
+        otherPartyContext += otherPremiseContext;
+    }
+    const result = {
+        viewerContext,
+        otherPartyContext,
+        matchReasoning,
+        category: interp.category ?? "connection",
+        confidence: typeof interp.confidence === "number"
+            ? interp.confidence
+            : parseFloat(String(interp.confidence ?? 0)) || 0,
+        signalsSummary,
+        indexName: indexRecord?.title ?? contextIndexId ?? "",
+        viewerRole: myActor.role ?? "party",
+        isIntroduction,
+        introducerName,
+    };
+    return result;
+}