@indexnetwork/protocol 14.3.2-rc.477.1 → 16.1.1-rc.478.1

package/dist/opportunities/application/opportunity.presentation.d.ts

@@ -0,0 +1,399 @@
+/**
+ * The opportunity presentation cluster.
+ *
+ * One file for the whole path from a persisted opportunity to the copy a user
+ * reads: the pure text transforms, the cache-key builders, the safe-fallback
+ * pipeline, and the LLM presenter itself. They were four modules that only ever
+ * called each other in one direction, and following a card's copy meant hopping
+ * between them.
+ *
+ * Sections, in dependency order:
+ *   1. Pure presentation transforms
+ *   2. Presentation cache keys
+ *   3. Safe-presentation pipeline (fallbacks that never leak raw reasoning)
+ *   4. OpportunityPresenter (LLM card and chat copy)
+ */
+import { z } from "zod";
+import type { Opportunity } from "../../shared/interfaces/database.interface.js";
+import type { ChatGraphCompositeDatabase } from "../../shared/interfaces/database.interface.js";
+import type { NegotiationContext } from "./negotiation-context.loader.js";
+/**
+ * Pure presentation layer for opportunities.
+ * Generates title, description, and CTA based on viewer context — no DB access.
+ */
+export interface OpportunityPresentation {
+    title: string;
+    description: string;
+    callToAction: string;
+}
+export interface UserInfo {
+    id: string;
+    name: string;
+    avatar: string | null;
+}
+/**
+ * Generate presentation copy for an opportunity based on viewer context.
+ * Pure function — no side effects, no database access.
+ */
+export declare function presentOpportunity(opp: Opportunity, viewerId: string, otherPartyInfo: UserInfo, introducerInfo: UserInfo | null, format: 'card' | 'email' | 'notification'): OpportunityPresentation;
+export declare function stripUuids(text: string): string;
+/**
+ * Truncate user-facing text to at most `maxChars` without cutting mid-word.
+ *
+ * Prefers a sentence boundary, then a word boundary, and only falls back to a
+ * hard slice if no boundary exists within the limit. An ellipsis is appended
+ * when the text is actually shortened. Used by presenter fallbacks so a degraded
+ * card never shows a sentence chopped mid-word (e.g. "His focus on 'indiv").
+ */
+export declare function truncateAtBoundary(text: string, maxChars: number): string;
+/**
+ * Strips introducer mentions from opportunity summary text.
+ * Removes patterns like:
+ * - "[Introducer] introduced you to [Counterpart]"
+ * - "[Introducer] thinks you should meet [Counterpart]"
+ * - "[Introducer] connected you to [Counterpart]"
+ * - "[Introducer] suggested you meet [Counterpart]"
+ *
+ * @param text - The text to clean (personalizedSummary)
+ * @param introducerName - Full name of the introducer to strip
+ * @returns Text with introducer mentions removed, counterpart preserved
+ */
+export declare function stripIntroducerMentions(text: string, introducerName: string | undefined): string;
+/**
+ * Returns viewer-centric main text for an opportunity card.
+ * Prefers the part of the reasoning that describes the counterpart (the person
+ * on the card), so the viewer sees an introduction to the counterpart rather
+ * than a description of themselves.
+ *
+ * @param reasoning - Raw interpretation.reasoning (may describe both parties).
+ * @param counterpartName - Display name of the suggested connection (e.g. "Alex Chen").
+ * @param maxChars - Max length of returned string (default MINIMAL_MAIN_TEXT_MAX_CHARS).
+ * @param viewerName - Optional display name of the viewer (signed-in user). When provided, sentences or prefixes describing the viewer are skipped so the card introduces the counterpart, not the viewer.
+ * @param introducerName - Optional display name of the introducer. When provided, introducer phrases (e.g., "X introduced you to...") are stripped from the summary to keep the body text focused on match quality.
+ * @returns Viewer-centric snippet mentioning the counterpart when possible; if counterpartName is empty, returns reasoning truncated to maxChars. Never null; may be "A suggested connection." when reasoning is empty.
+ */
+export declare function viewerCentricCardSummary(reasoning: string, counterpartName: string, maxChars?: number, viewerName?: string, introducerName?: string): string;
+/**
+ * Generates a short narrator remark from opportunity reasoning for the narrator chip.
+ * Used by the minimal (no-LLM) card path so each card gets a unique remark
+ * instead of the same static text.
+ *
+ * Extracts domain keywords (e.g. "AI", "design", "machine learning") from the
+ * reasoning and frames them in a short template like "Shared interest in AI and design."
+ *
+ * This is a regex-based heuristic — an alternative is OpportunityPresenter.presentCard()
+ * which generates narratorRemark via LLM with much higher quality (already used by
+ * home.graph.ts and opportunity.discover.ts). See buildMinimalOpportunityCard() in
+ * opportunity.tools.ts for the trade-off discussion.
+ *
+ * @param reasoning - Raw interpretation.reasoning text.
+ * @param counterpartName - Display name of the counterpart (stripped from output).
+ * @param viewerName - Optional display name of the viewer (stripped from output).
+ * @returns A short remark (max ~80 chars) suitable for the narrator chip. Never truncated with "...".
+ */
+export declare function narratorRemarkFromReasoning(reasoning: string, counterpartName: string, viewerName?: string): string;
+/** Cache namespace for opportunity presentation copy. Bump to invalidate copy safety changes. */
+export declare const OPPORTUNITY_PRESENTATION_CACHE_VERSION = "v2";
+export declare function buildRadarCardPresentationCacheKey(opportunityId: string, status: string, viewerId: string): string;
+export declare function buildDeliveryCardPresentationCacheKey(opportunityId: string, status: string, viewerId: string): string;
+export declare function buildApiChatCardPresentationCacheKey(opportunityId: string, viewerId: string): string;
+/**
+ * Shared safe-presentation primitive for all user-facing opportunity surfaces.
+ *
+ * Historically every surface (radar, list/discover cards, minimal chat
+ * cards, notification emails/Telegram, chat context, delivery cards) invented
+ * its own fallback chain for the case where genuine LLM presenter output is
+ * unavailable — some sliced raw `interpretation.reasoning` with no
+ * sanitization at all. This module is the single standard:
+ *
+ *   raw reasoning
+ *     → whitespace-normalize
+ *     → viewer-centric rewrite (incl. UUID stripping + introducer-mention stripping)
+ *     → boundary-aware truncation
+ *     → per-surface empty-text default
+ *
+ * Surfaces choose *policy* (send a sanitized fallback vs skip entirely) via
+ * `allowFallback`; they no longer choose (or forget) sanitization steps.
+ *
+ * See `packages/protocol/src/opportunity/AGENTS.md` for the review checklist this
+ * module exists to satisfy.
+ */
+/** Default max length for fallback summaries (matches presenter internal fallback). */
+export declare const SAFE_FALLBACK_MAX_CHARS = 300;
+/** Default copy when no reasoning text is available at all. */
+export declare const DEFAULT_EMPTY_FALLBACK_TEXT = "A promising connection.";
+/** Default headline for fallback presentations (matches presenter internal fallback). */
+export declare const DEFAULT_FALLBACK_HEADLINE = "A promising connection";
+/** Default CTA for fallback presentations (matches presenter internal fallback). */
+export declare const DEFAULT_FALLBACK_ACTION = "Take a look and decide whether to reach out.";
+export interface SafeFallbackOptions {
+    /** Display name of the counterpart shown on the card (enables viewer-centric rewrite). */
+    counterpartName?: string;
+    /** Display name of the viewer; sentences describing the viewer are skipped/rewritten to "you". */
+    viewerName?: string;
+    /** Introducer display name; introducer mentions are stripped from the summary body. */
+    introducerName?: string | null;
+    /** Max output length (boundary-aware). Default {@link SAFE_FALLBACK_MAX_CHARS}. */
+    maxChars?: number;
+    /** Copy returned when reasoning is empty/blank. Default {@link DEFAULT_EMPTY_FALLBACK_TEXT}. */
+    emptyText?: string;
+}
+/**
+ * Produce safe user-facing fallback copy from raw match reasoning.
+ *
+ * This is the ONE sanitization standard: UUID stripping, introducer-mention
+ * stripping, and viewer-centric rewrite (via {@link viewerCentricCardSummary}),
+ * followed by whitespace normalization and boundary-aware truncation (via
+ * {@link truncateAtBoundary}). Never returns raw reasoning verbatim beyond
+ * these guarantees, and never returns an empty string.
+ *
+ * @param rawReasoning - Raw `interpretation.reasoning` / `matchReason` text (may be null/undefined).
+ * @param opts - Per-surface knobs (names for rewrite, max length, empty-text copy).
+ */
+export declare function safeFallbackSummary(rawReasoning: string | null | undefined, opts?: SafeFallbackOptions): string;
+/** Minimal presenter-output shape the primitive inspects (subset of CardPresentationResult). */
+export interface SafePresentationCandidate {
+    headline?: string;
+    personalizedSummary?: string;
+    suggestedAction?: string;
+    /** Set by OpportunityPresenter when its LLM call failed and it returned fallback-shaped copy. */
+    isFallback?: boolean;
+}
+/** Opportunity-ish source object accepted by {@link getSafePresentationOrSkip}. */
+export interface SafePresentationSource {
+    /** Presenter output attached to the record, when available. */
+    homeCardPresentation?: SafePresentationCandidate | null;
+    /** Pre-truncated raw reasoning carried on discovery/list card data. */
+    matchReason?: string | null;
+    /** Full opportunity interpretation, when the caller holds the record. */
+    interpretation?: {
+        reasoning?: string | null;
+    } | null;
+}
+export interface SafePresentationOptions extends SafeFallbackOptions {
+    /**
+     * Policy switch: when false, return null instead of fallback copy so the
+     * surface can skip rendering entirely (e.g. scheduled digests where sending
+     * degraded copy is worse than sending nothing). Default true.
+     */
+    allowFallback?: boolean;
+}
+/** Resolved safe presentation for a surface to render. */
+export interface SafePresentation {
+    headline: string;
+    summary: string;
+    suggestedAction: string;
+    /** True when copy was derived from raw reasoning rather than genuine LLM presenter output. */
+    isFallback: boolean;
+}
+/**
+ * Resolve the safe user-facing presentation for an opportunity, or signal skip.
+ *
+ * Resolution order:
+ * 1. Genuine presenter output (`homeCardPresentation` present, non-empty, and
+ *    NOT tagged `isFallback` by the presenter) — claim-validated before return.
+ * 2. Otherwise, if `allowFallback` (default true): sanitized fallback copy
+ *    built from `matchReason` / `interpretation.reasoning` via
+ *    {@link safeFallbackSummary}.
+ * 3. Otherwise `null` — the surface must skip this opportunity.
+ *
+ * Raw `interpretation.reasoning` / `matchReason` never reaches the caller
+ * unsanitized through this function.
+ */
+export declare function getSafePresentationOrSkip(source: SafePresentationSource, opts?: SafePresentationOptions): SafePresentation | null;
+/**
+ * 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.
+ */
+/**
+ * Minimal database interface required by gatherPresenterContext.
+ * Any database adapter that implements these three methods can be passed.
+ */
+export type PresenterDatabase = Pick<ChatGraphCompositeDatabase, "getProfile" | "getActiveIntents" | "getNetwork" | "getPremisesForUser">;
+declare const PresentationSchema: z.ZodObject<{
+    headline: z.ZodString;
+    personalizedSummary: z.ZodString;
+    suggestedAction: z.ZodString;
+    greeting: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    personalizedSummary: string;
+    headline: string;
+    suggestedAction: string;
+    greeting: string;
+}, {
+    personalizedSummary: string;
+    headline: string;
+    suggestedAction: string;
+    greeting: string;
+}>;
+export type OpportunityPresentationResult = z.infer<typeof PresentationSchema> & {
+    /** True when any output field used resilience fallback copy. */
+    isFallback?: boolean;
+    /** Diagnostic category; never changes production fallback policy. */
+    fallbackReason?: "timeout" | "error" | "sanitization";
+};
+/** Input for card presenter call; extends PresenterInput with optional mutual intent count. */
+export interface CardPresenterInput extends PresenterInput {
+    /** Number of overlapping intents (for generating mutualIntentsLabel). */
+    mutualIntentCount?: number;
+    /**
+     * Snapshot of the opportunity's negotiation, if one exists. When status is
+     * `negotiating`, the presenter returns a templated chip without invoking
+     * the LLM. For `pending`/`stalled`/`accepted`/`rejected`, the full
+     * transcript and outcome ground the LLM's explanation.
+     */
+    negotiationContext?: NegotiationContext;
+}
+/** LLM-generated fields for card presentation (buttons are hardcoded by callers, not LLM-generated). */
+export declare const CardLLMSchema: z.ZodObject<{
+    headline: z.ZodString;
+    personalizedSummary: z.ZodString;
+    digestSummary: z.ZodString;
+    suggestedAction: z.ZodString;
+    narratorRemark: z.ZodString;
+    mutualIntentsLabel: z.ZodString;
+    greeting: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    personalizedSummary: string;
+    headline: string;
+    suggestedAction: string;
+    greeting: string;
+    digestSummary: string;
+    narratorRemark: string;
+    mutualIntentsLabel: string;
+}, {
+    personalizedSummary: string;
+    headline: string;
+    suggestedAction: string;
+    greeting: string;
+    digestSummary: string;
+    narratorRemark: string;
+    mutualIntentsLabel: string;
+}>;
+/** LLM-generated result from presentCard (callers append button labels from opportunity.constants). */
+export type CardLLMResult = z.infer<typeof CardLLMSchema> & {
+    /**
+     * True when the LLM call failed and this is fallback-shaped copy built from
+     * raw match reasoning. Callers with strict quality requirements (digests,
+     * long-lived caches) should check this before sending/persisting — fallback
+     * output is otherwise indistinguishable from genuine LLM output.
+     */
+    isFallback?: boolean;
+};
+/** Full card display contract including hardcoded button labels (assembled by callers). */
+export type CardPresentationResult = CardLLMResult & {
+    primaryActionLabel: string;
+    secondaryActionLabel: string;
+};
+/** Input for a single presenter call (all context pre-assembled). */
+export interface PresenterInput {
+    viewerContext: string;
+    otherPartyContext: string;
+    matchReasoning: string;
+    category: string;
+    confidence: number;
+    signalsSummary: string;
+    indexName: string;
+    viewerRole: string;
+    opportunityStatus?: string;
+    /** True when this opportunity was created via an explicit introduction (not automatic discovery). */
+    isIntroduction?: boolean;
+    /** Name of the person who made the introduction, if applicable. */
+    introducerName?: string;
+}
+export declare class OpportunityPresenter {
+    private model;
+    private homeCardModel;
+    constructor();
+    private invokeWithTimeout;
+    /**
+     * Generate personalized presentation for a single opportunity.
+     */
+    present(input: PresenterInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<OpportunityPresentationResult>;
+    /**
+     * Generate LLM-powered 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.
+     */
+    presentCard(input: CardPresenterInput): Promise<CardLLMResult>;
+    /**
+     * Process multiple opportunities in parallel with bounded concurrency.
+     */
+    presentBatch(inputs: PresenterInput[], options?: {
+        concurrency?: number;
+    }): Promise<OpportunityPresentationResult[]>;
+    /**
+     * Process multiple opportunities as cards in parallel with bounded concurrency.
+     * Returns full card display contracts (headline, body, narrator remark, action labels, mutual-intent label).
+     */
+    presentCardBatch(inputs: CardPresenterInput[], options?: {
+        concurrency?: number;
+    }): Promise<CardLLMResult[]>;
+}
+/**
+ * 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 declare function summarizeSignalsForPresenter(signals: Opportunity['interpretation']['signals']): string;
+/**
+ * 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 a radar 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 declare function gatherPresenterContext(database: PresenterDatabase, opportunity: Opportunity, viewerId: string, displayCounterpartUserId?: string): Promise<PresenterInput>;
+/**
+ * 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;
+    profileUrl?: string | undefined;
+    /** Universal link that opens this opportunity's card (`/o/<id>`). */
+    appUrl?: 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, appUrl and profileUrl
+ * when present, feedCategory when present) and includes `opportunityId` for
+ * every card so the agent can act via the tools. The trailing instruction
+ * reminds the agent to synthesize in natural language, to surface the `appUrl`
+ * verbatim as the one link that opens the card, and to fabricate no other URL.
+ * 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;
+export {};