@indexnetwork/protocol 65.0.0 → 66.0.0-rc.609.1

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

@@ -2,186 +2,26 @@
  * 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.
+ * reads: the cache-key builders and the LLM presenter itself. All user-facing
+ * copy comes from the presenter; there is no deterministic fallback.
  *
  * 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)
+ *   1. Presentation cache keys
+ *   2. OpportunityPresenter (LLM card and chat copy)
  */
 import { z } from "zod";
 import type { Opportunity } from "../../platform/database.js";
 import type { CompositeDatabase } from "../../platform/database.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, 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;
-/**
- * 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.
- * @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): 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.
- *
- * @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, focusedViewerIntentId?: string): string;
+export declare function buildOpportunityCardCacheKey(opportunityId: string, status: string, viewerId: string, focusedViewerIntentId?: 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)
- *     → 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/s./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;
-    /** 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,
- * 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
  *
@@ -201,22 +41,17 @@ declare const PresentationSchema: z.ZodObject<{
     suggestedAction: z.ZodString;
     greeting: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    personalizedSummary: string;
     headline: string;
+    personalizedSummary: string;
     suggestedAction: string;
     greeting: string;
 }, {
-    personalizedSummary: string;
     headline: string;
+    personalizedSummary: 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";
-};
+export type OpportunityPresentationResult = z.infer<typeof PresentationSchema>;
 /** Input for card presenter call; extends PresenterInput with optional mutual intent count. */
 export interface CardPresenterInput extends PresenterInput {
     /** Number of overlapping intents (for generating mutualIntentsLabel). */
@@ -238,30 +73,22 @@ export declare const CardLLMSchema: z.ZodObject<{
     mutualIntentsLabel: z.ZodString;
     greeting: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    personalizedSummary: string;
     headline: string;
+    personalizedSummary: string;
     suggestedAction: string;
     greeting: string;
     narratorRemark: string;
     mutualIntentsLabel: string;
 }, {
-    personalizedSummary: string;
     headline: string;
+    personalizedSummary: string;
     suggestedAction: string;
     greeting: 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;
-};
+export type CardLLMResult = z.infer<typeof CardLLMSchema>;
 /** Full card display contract including hardcoded button labels (assembled by callers). */
 export type CardPresentationResult = CardLLMResult & {
     primaryActionLabel: string;
@@ -286,6 +113,11 @@ export declare class OpportunityPresenter {
     private invokeWithTimeout;
     /**
      * Generate personalized presentation for a single opportunity.
+     *
+     * @param input - Pre-assembled presenter context.
+     * @param options - Optional abort signal.
+     * @returns The LLM-generated presentation.
+     * @throws When the LLM call fails, times out, or returns invalid output.
      */
     present(input: PresenterInput, options?: {
         signal?: AbortSignal;
@@ -297,6 +129,10 @@ export declare class OpportunityPresenter {
      * When `negotiationContext.status === 'negotiating'`, returns a templated
      * chip synchronously without invoking the LLM — the card just reflects
      * "negotiation in progress" at that point.
+     *
+     * @param input - Pre-assembled card presenter context.
+     * @returns The LLM-generated card copy.
+     * @throws When the LLM call fails, times out, or returns invalid output.
      */
     presentCard(input: CardPresenterInput): Promise<CardLLMResult>;
     /**
@@ -323,7 +159,7 @@ export declare function summarizeSignalsForPresenter(signals: Opportunity['inter
  * Gather all context needed for the presenter from the database.
  * Fetches viewer profile, viewer intents, other party profile(s), and network 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.
+ * @param displayCounterpartUserId - When set (e.g. for an opportunity card), only this counterpart is included in otherPartyContext so the presenter writes about the person on the card.
  * @param focusedViewerIntentId - When set, include only that active intent in viewer context.
  */
 export declare function gatherPresenterContext(database: PresenterDatabase, opportunity: Opportunity, viewerId: string, displayCounterpartUserId?: string, focusedViewerIntentId?: string): Promise<PresenterInput>;