@indexnetwork/protocol 6.12.1-rc.404.1 → 6.13.22-rc.405.1

package/dist/opportunity/opportunity.tools.js

@@ -1,2240 +1,5 @@
-import { z } from "zod";
-import { requestContext } from "../shared/observability/request-context.js";
-import { success, error, UUID_REGEX } from "../shared/agent/tool.helpers.js";
-import { deriveDiscoveryNetworkIds, focusedIntentId, focusedNetworkId, focusedNetworkLabel } from "../shared/agent/tool.scope.js";
-import { MINIMAL_MAIN_TEXT_MAX_CHARS, getPrimaryActionLabel, SECONDARY_ACTION_LABEL } from "./opportunity.labels.js";
-import { narratorRemarkFromReasoning, stripUuids } from "./opportunity.presentation.js";
-import { safeFallbackSummary, getSafePresentationOrSkip } from "./opportunity.safe-presentation.js";
-import { stripUnsupportedOpportunityClaims } from "./opportunity.claim-safety.js";
-import { runDiscoverFromQuery, continueDiscovery } from "./opportunity.discover.js";
-import { isDiscoveryQuestionsEnabled, isUptakeGuardEnabled } from "../questioner/questioner.env.js";
-import { OpportunityPresenter, gatherPresenterContext } from "./opportunity.presenter.js";
-import { loadNegotiationContext } from "./negotiation-context.loader.js";
-function stripLeadingNarratorName(remark, narratorName) {
-    let t = remark.trim();
-    if (!t || !narratorName.trim())
-        return remark;
-    const name = narratorName.trim();
-    const nameLower = name.toLowerCase();
-    for (;;) {
-        const lower = t.toLowerCase();
-        if (!lower.startsWith(nameLower))
-            break;
-        // Require a word boundary after the name so a short name like "Al" does not
-        // mangle a longer word ("Always …" → "ways …"). The char after the name must
-        // be a separator (sentence/clause punctuation or whitespace) or end of string.
-        // Keep this set in sync with the separator stripped from `rest` below.
-        const boundary = t.charAt(name.length);
-        if (boundary && !/[\s.:,\-–—]/.test(boundary))
-            break;
-        const rest = t.slice(name.length).replace(/^\s*[.:,\-–—]\s*/i, '').trim();
-        if (rest.length === 0 || rest === t)
-            break;
-        t = rest;
-    }
-    return t;
-}
-import { protocolLogger } from "../shared/observability/protocol.logger.js";
-import { selectByComposition, deduplicateByPerson, selectDigestCandidates } from "./opportunity.utils.js";
-import { mergePendingQuestions } from "./opportunity.pending-questions.js";
-import { invokeWithAbortSignal } from "../shared/agent/model-signal.js";
-const logger = protocolLogger("ChatTools:Opportunity");
-const discoverOpportunitiesLog = protocolLogger("ChatTools:Opportunity:discover_opportunities");
 /**
- * Pure status × role → ConnectLinkKind matrix.
- *
- * Returns the kind of short-link the viewer can act on directly, or `null` if
- * no direct link makes sense for this combination. Non-null kinds map to:
- *
- * - `connect` — pending opp where viewer is a non-introducer party. Clicking
- *   flips the opp to accepted and opens the chat with the counterpart.
- * - `approve_introduction` — draft or latent opp where viewer is an unapproved
- *   introducer. Clicking flips approved=true and triggers negotiation. The
- *   `draft` case comes from `discover_opportunities` intro mode; the `latent`
- *   case comes from background-discovered connector-flow cards surfaced in
- *   `list_opportunities`. In both, status remains pre-send and the `/c/<code>`
- *   link is the only MCP path to approve.
- * - `outreach` — accepted opp where viewer is a non-introducer party.
- *   Clicking opens the existing chat (no state change).
- * - `send_direct` — draft or latent opp where viewer is a non-introducer
- *   party. Issued by `discover_opportunities` in direct (no-introducer)
- *   mode: the match has already passed evaluation, the row exists in
- *   draft state, and the sender just needs to release it. Clicking flips
- *   the opp straight to accepted and opens the chat with a greeting —
- *   same handler path as `connect`. The counterpart's side sees the new
- *   accepted opp and can engage or ignore.
+ * Thin backward-compat shim — IND-551.
+ * Canonical location: opportunity/application/opportunity.tools.ts
  */
-export function resolveActionableLinkKind(input) {
-    const { status, viewerRole, viewerApproved, viewerActedAt } = input;
-    const isIntroducer = viewerRole === "introducer";
-    const hasViewerActed = !!viewerActedAt;
-    if (status === "accepted") {
-        return isIntroducer ? null : "outreach";
-    }
-    if (status === "pending") {
-        return isIntroducer || hasViewerActed ? null : "connect";
-    }
-    if (status === "draft" || status === "latent") {
-        if (!isIntroducer)
-            return hasViewerActed ? null : "send_direct";
-        return viewerApproved === true ? null : "approve_introduction";
-    }
-    return null;
-}
-/**
- * Build the agent-facing profile link for a counterpart — always the Index web
- * profile URL with `?link_preview=false`. Returns `undefined` only if
- * `frontendUrl` is not configured.
- *
- * The `?link_preview=false` hint is honored by chat-gateway runtimes (e.g.
- * OpenClaw's Telegram delivery) that strip link previews when present in the
- * URL; consistent placement matters more than Telegram's own handling.
- *
- * Trailing slashes on frontendUrl are stripped before concatenation.
- */
-export function buildProfileUrl(counterpartUserId, frontendUrl) {
-    // The profile link is always the Index web profile, regardless of the
-    // counterpart's socials or the viewer's surface. Surface-aware Telegram
-    // deep-linking lives on the connect URL (`/c/:code`) — the connect-link
-    // controller resolves that to a pre-messaged t.me link — never here.
-    if (!frontendUrl)
-        return undefined;
-    const base = frontendUrl.replace(/\/+$/, "");
-    return `${base}/u/${counterpartUserId}?link_preview=false`;
-}
-/**
- * Build the deep-link to an opportunity's A2A negotiation trace
- * (`/chat/:conversationId`) so users can see *what negotiation led to* the
- * surfaced opportunity (EDG-50/EDG-51). Returns `undefined` when `frontendUrl`
- * is unset or there is no negotiation conversation to link to.
- *
- * The `?link_preview=false` hint mirrors `buildProfileUrl` — chat-gateway
- * runtimes (e.g. Telegram delivery) strip link previews when it is present.
- * Trailing slashes on `frontendUrl` are stripped before concatenation.
- */
-export function buildNegotiationUrl(conversationId, frontendUrl) {
-    if (!frontendUrl || !conversationId)
-        return undefined;
-    const base = frontendUrl.replace(/\/+$/, "");
-    return `${base}/chat/${conversationId}?link_preview=false`;
-}
-/**
- * Mint a short-link for `card` if the (status, viewerRole, viewerApproved)
- * combination is actionable; mutate the card in place with `acceptUrl`,
- * `profileUrl`, and `feedCategory`. No-op (and no DB call) if not actionable.
- *
- * Swallows mint errors after logging — the card is still returned without an
- * `acceptUrl`, matching the prior `list_opportunities` resilience behavior.
- */
-export async function attachActionableLinks(card, opts) {
-    // profileUrl is independent of whether the (status, viewerRole) combination
-    // is actionable — every counterpart has a profile page worth linking to,
-    // even on a fresh draft where there is no acceptUrl yet. Setting it before
-    // the early-return below means cards from non-actionable combinations
-    // (e.g. draft + party in `discover_opportunities` direct mode) still carry
-    // the profile link the agent needs to render. Without this, the agent gets
-    // a name with no URL attached and tends to fabricate one.
-    const profileUrl = buildProfileUrl(opts.counterpartUserId, opts.frontendUrl);
-    if (profileUrl)
-        card.profileUrl = profileUrl;
-    const kind = resolveActionableLinkKind({
-        status: card.status,
-        viewerRole: card.viewerRole,
-        viewerApproved: opts.viewerApproved,
-        viewerActedAt: opts.viewerActedAt,
-    });
-    logger.info("Opportunity actionability decision", {
-        opportunityId: card.opportunityId,
-        status: card.status,
-        viewerRole: card.viewerRole,
-        viewerApproved: opts.viewerApproved,
-        viewerActedAt: opts.viewerActedAt,
-        kind: kind ?? "none",
-    });
-    if (kind === null)
-        return;
-    try {
-        const { url } = await opts.mintConnectLink({
-            userId: opts.viewerId,
-            opportunityId: card.opportunityId,
-            kind,
-            greeting: null,
-            preferredSurface: opts.preferredSurface,
-        });
-        card.acceptUrl = url;
-        card.feedCategory = card.viewerRole === "introducer" ? "connector-flow" : "connection";
-    }
-    catch (err) {
-        logger.warn("Failed to mint MCP opportunity link — surfacing card without acceptUrl/feedCategory; profileUrl is still attached", {
-            opportunityId: card.opportunityId,
-            kind,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-}
-/**
- * Statuses for which `update_opportunity` must refuse mutations.
- * - `accepted` / `rejected` / `expired`: terminal outcomes.
- * - `negotiating`: in-flight system-driven turn; user-driven mutations would
- *   race the negotiation graph. The graph itself transitions out of this state.
- */
-const UPDATE_OPPORTUNITY_BLOCKED_STATUSES = new Set([
-    "accepted",
-    "rejected",
-    "expired",
-    "negotiating",
-]);
-function publicUptakeQuestion(question) {
-    return {
-        id: question.id,
-        title: question.title,
-        prompt: question.prompt,
-        options: question.options,
-        multiSelect: question.multiSelect,
-    };
-}
-function uptakeAdvisory(opportunityId, questions) {
-    return JSON.stringify({
-        success: false,
-        error: "Resolve the pending uptake questions or explicitly continue anyway.",
-        advisory: {
-            code: "unresolved_uptake_questions",
-            advisoryOnly: true,
-            opportunityId,
-            questions,
-            acknowledgedUptakeQuestionIds: questions.map((question) => question.id),
-        },
-    });
-}
-function matchesSelectedIntentScope(opportunity, viewerId, scope) {
-    if (scope?.scopeType !== 'intent' || !scope.scopeId)
-        return true;
-    if (opportunity.detection?.triggeredBy === scope.scopeId)
-        return true;
-    return opportunity.actors.some((actor) => actor.userId === viewerId && actor.intent === scope.scopeId);
-}
-/**
- * Maximum number of opportunity cards to show per chat response.
- * Sized for `selectByComposition` to fill both feed buckets — up to 3
- * connection + 3 connector-flow per the digest/ambient prompt rules.
- */
-const CHAT_DISPLAY_LIMIT = 6;
-/**
- * Wider fetch budget so `selectByComposition` has both buckets to balance
- * across, even when one category dominates the natural sort order.
- */
-const CHAT_FETCH_LIMIT = 30;
-/**
- * How many accepted opportunities to scan when building the digest's
- * accepted-counterpart suppression set. Wide enough to cover a month-long
- * popup's accept history without unbounded reads.
- */
-const ACCEPTED_SUPPRESSION_FETCH_LIMIT = 200;
-/** Markdown code fence (three backticks). Avoids embedding ``` in string literals so TS parser stays in sync. */
-const CODE_FENCE = String.fromCharCode(96, 96, 96);
-/**
- * Sanitize JSON string for use inside a markdown code fence (```). Escapes backticks
- * so embedded ``` cannot close the fence prematurely.
- */
-function sanitizeJsonForCodeFence(json) {
-    return json.replace(/`/g, "\\u0060");
-}
-/**
- * Build minimal opportunity card data for chat without calling the LLM presenter.
- * Uses only required fields from the opportunity record and counterpart name/avatar
- * so list_opportunities and discovery return quickly.
- *
- * Note: narratorChip.text is generated via regex heuristics (narratorRemarkFromReasoning)
- * rather than the OpportunityPresenter LLM. If narrator quality becomes an issue again,
- * consider making this function async and delegating to OpportunityPresenter.presentHomeCard()
- * which already produces a high-quality narratorRemark via LLM (used by the home graph
- * and discovery pipeline). The trade-off is 5-20s latency per card.
- *
- * Exported for use in tests (opportunity.tools.spec.ts).
- */
-export function buildMinimalOpportunityCard(opp, viewerId, counterpartUserId, counterpartName, counterpartAvatar, introducerName, introducerAvatar, viewerName, secondPartyName, secondPartyAvatar, secondPartyUserId, isCounterpartGhost) {
-    const viewerActor = opp.actors.find((a) => a.userId === viewerId);
-    const viewerRole = viewerActor?.role ?? "party";
-    const introducerActor = opp.actors.find((a) => a.role === "introducer" && a.userId !== viewerId);
-    const viewerIsIntroducer = opp.actors.some((a) => a.role === "introducer" && a.userId === viewerId);
-    const reasoning = opp.interpretation?.reasoning ?? "";
-    // Shared sanitization standard — see opportunity.safe-presentation.ts.
-    const mainText = safeFallbackSummary(reasoning, {
-        counterpartName,
-        viewerName,
-        introducerName: introducerName ?? undefined,
-        maxChars: MINIMAL_MAIN_TEXT_MAX_CHARS,
-        emptyText: "A suggested connection.",
-    });
-    const score = typeof opp.interpretation?.confidence === "number"
-        ? opp.interpretation.confidence
-        : undefined;
-    const narratorName = viewerIsIntroducer
-        ? "You"
-        : introducerName?.trim() || (introducerActor ? "Someone" : "Index");
-    const primaryActionLabel = getPrimaryActionLabel(viewerRole);
-    return {
-        opportunityId: opp.id,
-        userId: counterpartUserId,
-        name: counterpartName,
-        avatar: counterpartAvatar,
-        mainText,
-        cta: "Start a conversation to connect.",
-        headline: viewerIsIntroducer && secondPartyName
-            ? `${counterpartName} → ${secondPartyName}`
-            : `Connection with ${counterpartName}`,
-        primaryActionLabel,
-        secondaryActionLabel: SECONDARY_ACTION_LABEL,
-        mutualIntentsLabel: "Suggested connection",
-        narratorChip: {
-            name: narratorName,
-            text: narratorRemarkFromReasoning(reasoning, counterpartName, viewerName),
-            ...(viewerIsIntroducer
-                ? { userId: viewerId, avatar: null }
-                : introducerActor
-                    ? { userId: introducerActor.userId, avatar: introducerAvatar ?? null }
-                    : {}),
-        },
-        viewerRole,
-        score,
-        status: opp.status ?? "latent",
-        isGhost: isCounterpartGhost ?? false,
-        ...(viewerIsIntroducer && secondPartyName
-            ? {
-                secondParty: {
-                    name: secondPartyName,
-                    ...(secondPartyAvatar != null ? { avatar: secondPartyAvatar } : {}),
-                    ...(secondPartyUserId ? { userId: secondPartyUserId } : {}),
-                },
-            }
-            : {}),
-    };
-}
-/**
- * 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.
- */
-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;
-}
-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}`);
-}
-/**
- * Stable signature of a discovery request, used to coalesce duplicate MCP runs.
- * Two requests with the same signature describe the same discovery and should
- * share a single in-flight run rather than each spawning a fresh (expensive)
- * opportunity-graph execution. Text fields are normalized (trim + lowercase);
- * id lists are sorted so ordering does not matter.
- *
- * Encoded as JSON of a normalized object — NOT a delimiter join — so a
- * user-supplied string containing the delimiter can never make two distinct
- * requests collide. `hint` and each entity's `networkId` are included because
- * they change the discovery result (different reason / different shared network),
- * so requests that differ only in those must NOT coalesce. Natural-language
- * fields (`searchQuery`, `hint`) are lowercased; identifiers and the opaque
- * `continueFrom` pagination token are only trimmed (case-sensitive) so distinct
- * tokens never collapse together.
- */
-function discoveryRunSignature(input, scopeKey) {
-    const text = (s) => (s ?? "").trim().toLowerCase();
-    const id = (s) => (s ?? "").trim();
-    // Encode each entity as a JSON tuple string, then sort the strings — a stable
-    // total order with a correct comparator (default Array#sort on strings).
-    const entities = [...(input.entities ?? [])]
-        .map((e) => JSON.stringify([id(e.networkId), id(e.userId)]))
-        .sort();
-    return JSON.stringify({
-        searchQuery: text(input.searchQuery),
-        networkId: id(input.networkId),
-        intentId: id(input.intentId),
-        targetUserId: id(input.targetUserId),
-        introTargetUserId: id(input.introTargetUserId),
-        continueFrom: id(input.continueFrom),
-        hint: text(input.hint),
-        partyUserIds: [...(input.partyUserIds ?? [])].map((x) => x.trim()).sort(),
-        entities,
-        scope: scopeKey,
-    });
-}
-/**
- * Stable key for the resolved discovery scope of a request. Two requests
- * coalesce only when they resolve to the same focused discovery boundary. For
- * scoped contexts, that boundary is the scope envelope (`scopeType`/`scopeId`),
- * not the personal-inclusive allowed network reach used for self-owned writes.
- * Unscoped requests intentionally share a single empty-scope key; concrete
- * allowed reach is derived from memberships at execution time.
- */
-function discoveryScopeKey(ctx) {
-    return JSON.stringify({
-        scopeType: (ctx.scopeType ?? "").trim(),
-        scopeId: (ctx.scopeId ?? "").trim(),
-    });
-}
-function confirmDeliveryError(code, retryable, message) {
-    return JSON.stringify({ success: false, error: message, code, retryable });
-}
-export function createOpportunityTools(defineTool, deps) {
-    const { database, userDb, systemDb, graphs, cache } = deps;
-    const runDiscoveryFromQuery = deps.opportunityDiscovery?.runDiscoverFromQuery ??
-        runDiscoverFromQuery;
-    const continueOpportunityDiscovery = deps.opportunityDiscovery?.continueDiscovery ??
-        continueDiscovery;
-    const createOpportunityPresenter = deps.opportunityPresentation?.createPresenter ??
-        (() => new OpportunityPresenter());
-    const gatherOpportunityPresenterContext = deps.opportunityPresentation?.gatherPresenterContext ??
-        gatherPresenterContext;
-    const discoverOpportunities = defineTool({
-        name: "discover_opportunities",
-        description: "Discovers opportunities — connections between users based on complementary intents — and persists them as drafts. " +
-            "Opportunities are the core output of the discovery engine, representing potential valuable connections between people.\n\n" +
-            "**NOT for person lookup** — use read_user_contexts(query=name) to find people by name.\n\n" +
-            "**Four modes:**\n" +
-            "1. **Discovery** (most common): pass `searchQuery` and/or `networkId`. The system finds other users in shared networkes " +
-            "whose intents semantically complement the query. Uses HyDE embeddings and LLM evaluation for scoring.\n" +
-            "2. **Introduction**: pass `partyUserIds` (2+ user IDs) + `entities` (pre-gathered profiles and intents from shared networkes). " +
-            "You MUST call read_user_contexts and read_intents for each party BEFORE calling this. " +
-            "Optionally pass `hint` with the user's reason for the introduction.\n" +
-            "3. **Direct connection**: pass `targetUserId` + `searchQuery`. Creates an opportunity between the current user and one specific person.\n" +
-            "4. **Introducer discovery**: pass `introTargetUserId` (find matches FOR that person; current user becomes the introducer). " +
-            "Use when user asks 'who should I introduce to [person]?'\n\n" +
-            "**Returns:** In regular chat, opportunity code blocks (render as interactive cards) with opportunityId, match reasoning, confidence score, and status. " +
-            "In MCP contexts, starts an async discovery run and returns `discoveryRunId` with status `queued`. " +
-            "Then poll get_discovery_run with that id roughly every 5 seconds until status is `succeeded`, `failed`, or `cancelled`, and present its `result`. " +
-            "Do NOT call discover_opportunities again for the same request while a run is in progress — a repeat call with the same parameters " +
-            "returns the SAME in-progress run (with `coalesced: true`), not a new one. Keep polling the run id instead of starting new runs. " +
-            "All results start as drafts. Supports pagination via `continueFrom` for large result sets.\n\n" +
-            "**Next steps:** Use update_opportunity(opportunityId, status='pending') to send a draft to the other party.\n\n" +
-            "**Discovery-first rule.** For open-ended connection-seeking requests (\"find me a mentor\", " +
-            "\"who needs a React dev\", \"looking for investors\"), call this tool with `searchQuery` FIRST. " +
-            "Do NOT call create_intent for these phrasings — create_intent is only for when the user explicitly " +
-            "asks to \"create\", \"save\", \"add\", or \"remember\" a signal.\n\n" +
-            "**Personal-index scoping.** When the user says \"in my network\", \"from my contacts\", \"people I know\", " +
-            "or similar scoping language, pass the user's personal network ID (from memberships where `isPersonal: true`) " +
-            "as `networkId`. The personal network contains the user's contacts — scoping discovery to it restricts " +
-            "results to people the user already knows. Without this scoping language, omit networkId to let discovery " +
-            "run across all networks.\n\n" +
-            "**Introduction mode prerequisites.** When using `partyUserIds` + `entities`, YOU must pre-fetch each party's " +
-            "profile and intents before calling this tool. The entities array must include each party's userId, profile, " +
-            "intents from shared networkes, and the shared networkId. Call read_user_contexts, read_network_memberships, " +
-            "and read_intents for both parties first. The introducer (current user) must NOT appear in entities.\n\n" +
-            "**Signal-visibility follow-up.** If the response includes `suggestIntentCreationForVisibility: true` and " +
-            "`suggestedIntentDescription`, after presenting opportunity cards ask the user ONCE whether they'd also like " +
-            "to create a signal so others can find them. On yes, call create_intent with the suggested description. " +
-            "Never suggest this after introducer-mode (`introTargetUserId`) calls — the query describes the other person's " +
-            "needs, not the signed-in user's.",
-        querySchema: z.object({
-            continueFrom: z
-                .string()
-                .optional()
-                .describe("Pagination token: pass the discoveryId from a previous discover_opportunities result to evaluate the next batch of candidates. Do not combine with searchQuery or other mode parameters — when a fresh searchQuery is also present, the server ignores continueFrom and runs a fresh discovery."),
-            searchQuery: z
-                .string()
-                .optional()
-                .describe("Discovery mode: natural language description of what to look for (e.g. 'AI/ML engineers', 'startup advisors in fintech'). Drives semantic matching against other users' intents and profiles."),
-            networkId: z
-                .string()
-                .optional()
-                .describe("Network UUID to scope discovery to a specific community. Get from read_networks. In an network-scoped chat, omitting this runs discovery only in the scoped community; pass the personal network ID (from read_networks, isPersonal=true) only when the user explicitly asks to discover among contacts."),
-            intentId: z
-                .string()
-                .optional()
-                .describe("Optional intent UUID to use as the discovery source. The intent's description drives matching instead of searchQuery. Get from read_intents. Typically used by background processing, not direct agent calls."),
-            targetUserId: z
-                .string()
-                .optional()
-                .describe("Direct connection mode: create an opportunity with this specific user. Get the userId from read_user_contexts(query=name). Combine with searchQuery to explain the connection reason."),
-            introTargetUserId: z
-                .string()
-                .optional()
-                .describe("Introducer discovery mode: find matches FOR this user ID (the current user becomes the introducer). " +
-                "Get the userId from read_user_contexts(query=name). " +
-                "Use when the user asks 'who should I introduce to [person]?'. " +
-                "Do NOT combine with partyUserIds (that's full introduction mode)."),
-            partyUserIds: z
-                .array(z.string())
-                .optional()
-                .describe("Introduction mode: array of 2+ user IDs to introduce to each other. Get user IDs from read_user_contexts or read_network_memberships. Must also provide entities with pre-gathered profile/intent data."),
-            entities: z
-                .array(z.object({
-                userId: z.string(),
-                profile: z
-                    .object({
-                    name: z.string().optional(),
-                    bio: z.string().optional(),
-                    location: z.string().optional(),
-                    interests: z.array(z.string()).optional(),
-                    skills: z.array(z.string()).optional(),
-                    context: z.string().optional(),
-                })
-                    .optional(),
-                intents: z
-                    .array(z.object({
-                    intentId: z.string(),
-                    payload: z.string(),
-                    summary: z.string().optional(),
-                }))
-                    .optional(),
-                networkId: z
-                    .string()
-                    .describe("Shared network this entity's data comes from (required for intro mode)"),
-            }))
-                .optional()
-                .describe("Introduction mode: pre-gathered profile and intent data for each party being introduced. " +
-                "Each entry needs userId, networkId (the shared network), and optionally profile (name, bio, skills, interests) and intents (intentId, payload). " +
-                "Gather this data by calling read_user_contexts and read_intents for each party BEFORE calling discover_opportunities. " +
-                "All entities must share the same networkId (the shared network where both parties are members)."),
-            hint: z
-                .string()
-                .optional()
-                .describe("Introduction mode: the user's reason for making this introduction (e.g. 'both working on AI in healthcare', " +
-                "'complementary skills for a startup'). Helps the evaluator produce better match reasoning."),
-        }),
-        handler: async ({ context, query }) => {
-            const scopedNetworkId = focusedNetworkId(context) ?? context.networkId?.trim();
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            // Strict scope enforcement: when chat is network-scoped, only allow that index
-            if (scopedNetworkId &&
-                query.networkId?.trim() &&
-                query.networkId.trim() !== scopedNetworkId) {
-                return error(`This chat is scoped to ${scopedIndexLabel}. You can only create opportunities in this community.`);
-            }
-            // Distinguish an explicit `query.networkId` override (caller wants discovery
-            // scoped to one specific index) from an implicit scoped-chat context.
-            // Scoped-chat discovery stays focused to the scoped community only; the
-            // personal-inclusive allowed reach is reserved for self-owned writes.
-            const explicitIndexId = query.networkId?.trim() || undefined;
-            const effectiveIndexId = explicitIndexId;
-            if (effectiveIndexId && !UUID_REGEX.test(effectiveIndexId)) {
-                return error("Invalid network ID format.");
-            }
-            const contextIntentId = focusedIntentId(context);
-            const requestedIntentId = query.intentId?.trim() || undefined;
-            if (requestedIntentId != null && !UUID_REGEX.test(requestedIntentId)) {
-                return error("Invalid intent ID format.");
-            }
-            if (contextIntentId && requestedIntentId && requestedIntentId !== contextIntentId) {
-                return error("This chat is scoped to a different intent.");
-            }
-            const triggerIntentId = contextIntentId ?? requestedIntentId;
-            if (triggerIntentId) {
-                const triggerIntent = await systemDb.getIntent(triggerIntentId);
-                if (!triggerIntent || triggerIntent.userId !== context.userId) {
-                    return error("Intent not found or you are not authorized to use it for discovery.");
-                }
-                if (triggerIntent.archivedAt ||
-                    (triggerIntent.status != null && triggerIntent.status !== 'ACTIVE')) {
-                    return error("This intent is not active. Resume it before starting discovery.");
-                }
-            }
-            if (context.isMcp && deps.discoveryRuns && deps.discoveryRunQueue) {
-                // Coalesce: if an equivalent discovery is already queued/running for this
-                // user, return that run instead of spawning a duplicate. An over-eager
-                // MCP client that re-fires discover_opportunities (instead of polling
-                // get_discovery_run) would otherwise kick off a fresh, expensive
-                // opportunity-graph run on every call — the loop that drives the agent
-                // into provider rate limits.
-                const signature = discoveryRunSignature(query, discoveryScopeKey(context));
-                try {
-                    const active = await deps.discoveryRuns.listActive(context.userId);
-                    const existing = active.find((r) => discoveryRunSignature(r.input, discoveryScopeKey(r.context)) === signature);
-                    if (existing) {
-                        return success({
-                            status: existing.status === "running" ? "running" : "queued",
-                            discoveryRunId: existing.id,
-                            coalesced: true,
-                            message: `A discovery run for this exact request is already ${existing.status}. ` +
-                                `Do NOT call discover_opportunities again — keep calling get_discovery_run with ` +
-                                `discoveryRunId="${existing.id}" (about every 5 seconds) until it succeeds, fails, ` +
-                                `or is cancelled, then present its result.`,
-                        });
-                    }
-                }
-                catch {
-                    // listActive is a best-effort optimization; fall through to create on error.
-                }
-                const run = await deps.discoveryRuns.create({
-                    userId: context.userId,
-                    agentId: context.agentId ?? null,
-                    input: query,
-                    context: {
-                        userId: context.userId,
-                        userName: context.userName,
-                        userEmail: context.userEmail,
-                        ...(context.scopeType && context.scopeId ? { scopeType: context.scopeType, scopeId: context.scopeId } : scopedNetworkId ? { scopeType: 'network', scopeId: scopedNetworkId } : {}),
-                        ...(context.indexName ? { indexName: context.indexName } : {}),
-                        ...(context.sessionId ? { sessionId: context.sessionId } : {}),
-                        ...(context.agentId ? { agentId: context.agentId } : {}),
-                        ...(context.clientSurface ? { clientSurface: context.clientSurface } : {}),
-                    },
-                });
-                try {
-                    await deps.discoveryRunQueue.enqueue(run.id);
-                }
-                catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
-                    await deps.discoveryRuns.markFailed(run.id, message);
-                    return error(`Failed to enqueue discovery run: ${message}`);
-                }
-                return success({
-                    status: "queued",
-                    discoveryRunId: run.id,
-                    message: `Discovery started. Poll get_discovery_run with discoveryRunId="${run.id}" about every 5 seconds ` +
-                        `until status is succeeded, failed, or cancelled, then present its result. ` +
-                        `Do NOT call discover_opportunities again for this request while the run is in progress — ` +
-                        `a repeat call returns this same run, not a new one.`,
-                });
-            }
-            // ── Continuation mode ──
-            // `continueFrom` is a pagination token for resuming a prior discovery's
-            // cached candidates. When a caller (typically an MCP client's LLM) sends
-            // a fresh `searchQuery` alongside a stale `continueFrom`, treat it as a
-            // fresh search — the explicit search intent wins. Resuming against the
-            // stale session's exhausted cache silently produced the "No more
-            // matching opportunities found in the remaining candidates" response
-            // for users who expected fresh results (IND-305).
-            if (query.continueFrom && query.searchQuery?.trim()) {
-                logger.warn("discover_opportunities: dropping stale continueFrom in favor of fresh searchQuery", {
-                    userId: context.userId,
-                    continueFrom: query.continueFrom,
-                });
-            }
-            if (query.continueFrom && !query.searchQuery?.trim()) {
-                const _continueTraceEmitter = requestContext.getStore()?.traceEmitter;
-                const _graphStart = Date.now();
-                _continueTraceEmitter?.({ type: "graph_start", name: "opportunity" });
-                const result = await continueOpportunityDiscovery({
-                    opportunityGraph: graphs.opportunity,
-                    database,
-                    cache,
-                    userId: context.userId,
-                    discoveryId: query.continueFrom,
-                    expectedIndexId: scopedNetworkId,
-                    limit: 20,
-                    presenter: createOpportunityPresenter(),
-                    useHomeCardFormat: true,
-                    ...(context.sessionId ? { chatSessionId: context.sessionId } : {}),
-                });
-                const _graphMs = Date.now() - _graphStart;
-                _continueTraceEmitter?.({ type: "graph_end", name: "opportunity", durationMs: _graphMs });
-                const allDebugSteps = [...(result.debugSteps ?? [])];
-                if (!result.found) {
-                    return success({
-                        found: false,
-                        count: 0,
-                        message: result.message ?? "No more matching opportunities found in the remaining candidates.",
-                        summary: "No more matches found",
-                        ...(result.pagination ? { pagination: result.pagination } : {}),
-                        debugSteps: allDebugSteps,
-                        _graphTimings: [{ name: 'opportunity', durationMs: _graphMs, agents: [] }],
-                    });
-                }
-                // Continuation now negotiates just like fresh discovery. For MCP callers,
-                // surface only post-negotiation drafts; keep in-flight attempts count-only
-                // and never render rejected/stalled or fallback latent rows as cards.
-                let negotiatingCount = 0;
-                const continuationCards = context.isMcp
-                    ? (result.opportunities ?? []).filter((opportunity) => {
-                        if (opportunity.status === 'draft')
-                            return true;
-                        if (opportunity.status === 'negotiating') {
-                            negotiatingCount += 1;
-                            return false;
-                        }
-                        if (opportunity.status === 'rejected' || opportunity.status === 'stalled' || opportunity.status === 'latent') {
-                            return false;
-                        }
-                        discoverOpportunitiesLog.warn('unexpected continuation status — counting as negotiating', {
-                            opportunityId: opportunity.opportunityId,
-                            status: opportunity.status,
-                        });
-                        negotiatingCount += 1;
-                        return false;
-                    })
-                    : (result.opportunities ?? []);
-                // Build card data; cap at CHAT_DISPLAY_LIMIT (remaining feeds into pagination)
-                const allCardData = continuationCards.map((opp) => ({
-                    opportunityId: opp.opportunityId,
-                    userId: opp.userId,
-                    name: opp.name,
-                    avatar: opp.avatar,
-                    mainText: getSafePresentationOrSkip(opp, { counterpartName: opp.name })?.summary ?? "",
-                    cta: opp.homeCardPresentation?.suggestedAction,
-                    headline: opp.homeCardPresentation?.headline,
-                    primaryActionLabel: opp.homeCardPresentation?.primaryActionLabel,
-                    secondaryActionLabel: opp.homeCardPresentation?.secondaryActionLabel,
-                    mutualIntentsLabel: opp.homeCardPresentation?.mutualIntentsLabel,
-                    narratorChip: opp.narratorChip,
-                    viewerRole: opp.viewerRole,
-                    isGhost: opp.isGhost ?? false,
-                    score: opp.score,
-                    status: opp.status,
-                    viewerActedAt: opp.viewerActedAt,
-                }));
-                const displayedCards = allCardData.slice(0, CHAT_DISPLAY_LIMIT);
-                const extraFromCap = allCardData.length - displayedCards.length;
-                let message = buildOpportunityPresentation(displayedCards, {
-                    isMcp: context.isMcp ?? false,
-                    leadIn: `Found ${displayedCards.length} more potential connection(s).`,
-                });
-                if (context.isMcp && negotiatingCount > 0) {
-                    message = displayedCards.length > 0
-                        ? `${message}\n\n${negotiatingCount} more opportunit${negotiatingCount === 1 ? 'y is' : 'ies are'} still being evaluated — check back via \`list_opportunities\` shortly.`
-                        : `Found candidates, but they're still being evaluated. Try \`list_opportunities\` in a minute — ${negotiatingCount} pending.`;
-                }
-                else if (context.isMcp && displayedCards.length === 0) {
-                    message = 'No additional actionable matches were found in this continuation.';
-                }
-                const isIntroducerContinuation = !!query.introTargetUserId?.trim();
-                const totalRemaining = (result.pagination?.remaining ?? 0) + extraFromCap;
-                if (totalRemaining > 0 && result.pagination?.discoveryId) {
-                    message += `\n\nThere are ${totalRemaining} more candidates. Ask if the user wants to see more — they can say "show me more" and you should call discover_opportunities with continueFrom="${result.pagination.discoveryId}".`;
-                }
-                else if (displayedCards.length > 0 && isIntroducerContinuation) {
-                    message += `\n\nThese are all the introduction candidates I found for this person.`;
-                }
-                else if (displayedCards.length > 0) {
-                    message += `\n\nThese are all the connections I found. If the user wants to attract more connections, suggest they create a signal — e.g. "Would you like to create a signal so others looking for someone like you can find you?" If they agree, call create_intent with a description based on what they were searching for.`;
-                }
-                return success({
-                    found: true,
-                    count: displayedCards.length,
-                    message,
-                    summary: `Found ${displayedCards.length} more match(es)`,
-                    ...(result.pagination ? { pagination: result.pagination } : {}),
-                    debugSteps: allDebugSteps,
-                    _graphTimings: [{ name: 'opportunity', durationMs: _graphMs, agents: [] }],
-                });
-            }
-            // Normalize entity networkIds before any checks to avoid raw-vs-trimmed mismatches.
-            const normalizedEntities = query.entities?.map((e) => ({ ...e, networkId: e.networkId?.trim() }));
-            // Derive partyUserIds from entities when agent passes entities but omits partyUserIds (intro mode).
-            // Only derive when all entities share the same networkId to prevent cross-network introductions.
-            const partyUserIdsFromEntities = normalizedEntities &&
-                normalizedEntities.length >= 2 &&
-                normalizedEntities.every((e) => e.userId && e.networkId) &&
-                new Set(normalizedEntities.map((e) => e.networkId)).size === 1
-                ? [...new Set(normalizedEntities.map((e) => e.userId))]
-                : undefined;
-            const effectivePartyUserIds = query.partyUserIds && query.partyUserIds.length >= 2
-                ? query.partyUserIds
-                : (partyUserIdsFromEntities?.length ?? 0) >= 2
-                    ? partyUserIdsFromEntities
-                    : undefined;
-            // ── Introduction mode ── (validation and persistence via opportunity graph)
-            if (effectivePartyUserIds && effectivePartyUserIds.length >= 2) {
-                if (!normalizedEntities || normalizedEntities.length === 0) {
-                    return error("Introduction requires pre-gathered entity data. " +
-                        "First use read_network_memberships to find shared networks, " +
-                        "then read_user_contexts and read_intents for each party, " +
-                        "then pass the results as entities.");
-                }
-                const normalizedEntityNetworkIds = normalizedEntities
-                    .map((e) => e.networkId)
-                    .filter((id) => Boolean(id));
-                if (normalizedEntityNetworkIds.length !== normalizedEntities.length ||
-                    new Set(normalizedEntityNetworkIds).size !== 1) {
-                    return error("All entities must include the same shared networkId.");
-                }
-                const [primaryNetworkId] = normalizedEntityNetworkIds;
-                const introducedPartyUserIds = effectivePartyUserIds.filter((uid) => uid !== context.userId);
-                if (introducedPartyUserIds.length === 0) {
-                    return error("No counterpart to introduce. Provide at least one other user ID in partyUserIds (besides yourself).");
-                }
-                const evaluatorEntities = normalizedEntities.map((e) => ({
-                    userId: e.userId,
-                    profile: e.profile ?? {},
-                    intents: e.intents,
-                    networkId: e.networkId,
-                }));
-                const _introGraphStart = Date.now();
-                const _introTraceEmitter = requestContext.getStore()?.traceEmitter;
-                _introTraceEmitter?.({ type: "graph_start", name: "opportunity" });
-                const result = await invokeWithAbortSignal(graphs.opportunity, {
-                    operationMode: "create_introduction",
-                    userId: context.userId,
-                    networkId: primaryNetworkId,
-                    introductionEntities: evaluatorEntities,
-                    introductionHint: query.hint,
-                    requiredNetworkId: scopedNetworkId,
-                    options: {
-                        initialStatus: "draft",
-                        ...(context.sessionId ? { conversationId: context.sessionId } : {}),
-                    },
-                });
-                const _introGraphMs = Date.now() - _introGraphStart;
-                _introTraceEmitter?.({ type: "graph_end", name: "opportunity", durationMs: _introGraphMs });
-                if (result.error || !result.opportunities?.length) {
-                    return error(result.error ?? "Failed to create introduction.");
-                }
-                const created = result.opportunities[0];
-                const reasoning = created.interpretation?.reasoning ?? "A suggested connection.";
-                const confidence = typeof created.interpretation?.confidence === "number"
-                    ? created.interpretation.confidence
-                    : parseFloat(String(created.confidence ?? 0)) || 0;
-                const introducerUser = await userDb.getUser();
-                const firstPartyId = introducedPartyUserIds[0];
-                const firstEntity = query.entities?.find((e) => e.userId === firstPartyId);
-                const counterpartUser = firstPartyId
-                    ? await database.getUser(firstPartyId)
-                    : null;
-                const counterpartName = firstEntity?.profile?.name ?? firstPartyId ?? "Someone";
-                // Second party — used in the headline and arrow layout for the introducer view ("A → B")
-                const secondPartyId = introducedPartyUserIds[1];
-                const secondEntity = query.entities?.find((e) => e.userId === secondPartyId);
-                const secondPartyName = secondEntity?.profile?.name;
-                const secondPartyAvatar = secondEntity?.profile?.avatar ?? null;
-                const secondPartyUser = secondPartyId ? await database.getUser(secondPartyId) : null;
-                const viewerIsParty = effectivePartyUserIds.includes(context.userId);
-                const viewerRole = viewerIsParty ? "party" : "introducer";
-                const isCounterpartGhost = counterpartUser?.isGhost ?? false;
-                const primaryActionLabel = getPrimaryActionLabel(viewerRole);
-                const publicMatchReason = safeFallbackSummary(reasoning, {
-                    counterpartName,
-                    introducerName: introducerUser?.name ?? undefined,
-                    maxChars: MINIMAL_MAIN_TEXT_MAX_CHARS,
-                    emptyText: "A suggested connection.",
-                });
-                const narratorText = narratorRemarkFromReasoning(reasoning, counterpartName, introducerUser?.name ?? undefined);
-                const narratorChip = viewerIsParty
-                    ? {
-                        name: "Index",
-                        text: narratorText,
-                    }
-                    : {
-                        name: "You",
-                        text: narratorText,
-                        userId: context.userId,
-                    };
-                const headline = !viewerIsParty && secondPartyName
-                    ? `${counterpartName} → ${secondPartyName}`
-                    : `Connection with ${counterpartName}`;
-                const cardData = {
-                    opportunityId: created.id,
-                    userId: firstPartyId,
-                    name: counterpartName,
-                    avatar: counterpartUser?.avatar ??
-                        firstEntity?.profile
-                            ?.avatar ??
-                        null,
-                    mainText: safeFallbackSummary(reasoning, {
-                        counterpartName,
-                        // viewerName not available in this context; introducer name passed separately
-                        introducerName: introducerUser?.name ?? undefined,
-                        maxChars: MINIMAL_MAIN_TEXT_MAX_CHARS,
-                        emptyText: "A suggested connection.",
-                    }),
-                    cta: "Start a conversation to connect.",
-                    headline,
-                    primaryActionLabel,
-                    secondaryActionLabel: SECONDARY_ACTION_LABEL,
-                    mutualIntentsLabel: "Suggested connection",
-                    narratorChip,
-                    viewerRole,
-                    isGhost: isCounterpartGhost,
-                    score: confidence,
-                    status: created.status ?? "draft",
-                    ...(!viewerIsParty && secondPartyName
-                        ? {
-                            secondParty: {
-                                name: secondPartyName,
-                                avatar: secondPartyUser?.avatar ?? secondPartyAvatar,
-                                ...(secondPartyId ? { userId: secondPartyId } : {}),
-                            },
-                        }
-                        : {}),
-                };
-                if (context.isMcp && deps.mintConnectLink) {
-                    await attachActionableLinks(cardData, {
-                        viewerId: context.userId,
-                        viewerApproved: false,
-                        counterpartUserId: firstPartyId,
-                        mintConnectLink: deps.mintConnectLink,
-                        frontendUrl: deps.frontendUrl,
-                        preferredSurface: context.clientSurface,
-                    });
-                }
-                return success({
-                    found: true,
-                    count: 1,
-                    summary: "Draft introduction created",
-                    message: buildOpportunityPresentation([cardData], {
-                        isMcp: context.isMcp ?? false,
-                        leadIn: "Draft introduction created.",
-                        label: "opportunity",
-                    }),
-                    opportunities: [
-                        {
-                            opportunityId: created.id,
-                            matchReason: publicMatchReason,
-                            score: confidence,
-                            status: created.status ?? "draft",
-                        },
-                    ],
-                    _graphTimings: [{ name: 'opportunity', durationMs: _introGraphMs, agents: result.agentTimings ?? [] }],
-                });
-            }
-            // ── Discovery mode ──
-            const searchQuery = query.searchQuery?.trim() ?? "";
-            if (query.intentId != null && query.intentId !== "" && !UUID_REGEX.test(query.intentId.trim())) {
-                return error("Invalid intent ID format.");
-            }
-            let indexScope;
-            const _scopeGraphTimings = [];
-            if (effectiveIndexId) {
-                if (!UUID_REGEX.test(effectiveIndexId)) {
-                    return error("Invalid network ID format.");
-                }
-                const _scopeGraphStart = Date.now();
-                const _scopeIndexMembershipTraceEmitter = requestContext.getStore()?.traceEmitter;
-                _scopeIndexMembershipTraceEmitter?.({ type: "graph_start", name: "network_membership" });
-                const memberResult = await invokeWithAbortSignal(graphs.networkMembership, {
-                    userId: context.userId,
-                    networkId: effectiveIndexId,
-                    operationMode: "read",
-                });
-                const _scopeIndexMembershipMs = Date.now() - _scopeGraphStart;
-                _scopeIndexMembershipTraceEmitter?.({ type: "graph_end", name: "network_membership", durationMs: _scopeIndexMembershipMs });
-                _scopeGraphTimings.push({ name: 'network_membership', durationMs: _scopeIndexMembershipMs, agents: [] });
-                if (memberResult.error) {
-                    return error("Network not found or you are not a member.");
-                }
-                indexScope = [effectiveIndexId];
-            }
-            else if (context.scopeType === 'network' && context.scopeId) {
-                // Scoped chat: discovery is focused-network only. Self-owned writes may
-                // include personal networkes, but opportunity visibility must not.
-                const scopedDiscoveryIds = deriveDiscoveryNetworkIds({
-                    memberships: context.userNetworks,
-                    scopeType: context.scopeType,
-                    scopeId: context.scopeId,
-                });
-                indexScope = scopedDiscoveryIds;
-            }
-            else if (scopedNetworkId) {
-                // Scoped context: preserve focused-only discovery using the scope envelope.
-                indexScope = [scopedNetworkId];
-            }
-            else {
-                // No scope - use all networks (only in unscoped chat)
-                const _scopeGraphStart = Date.now();
-                const _scopeIndexTraceEmitter = requestContext.getStore()?.traceEmitter;
-                _scopeIndexTraceEmitter?.({ type: "graph_start", name: "index" });
-                const indexResult = await invokeWithAbortSignal(graphs.index, {
-                    userId: context.userId,
-                    operationMode: "read",
-                    showAll: true,
-                });
-                const _scopeIndexMs = Date.now() - _scopeGraphStart;
-                _scopeIndexTraceEmitter?.({ type: "graph_end", name: "index", durationMs: _scopeIndexMs });
-                _scopeGraphTimings.push({ name: 'index', durationMs: _scopeIndexMs, agents: [] });
-                if (indexResult.error) {
-                    return error(indexResult.error);
-                }
-                indexScope = (indexResult.readResult?.memberOf || []).map((m) => m.networkId);
-            }
-            const toolDebugSteps = [
-                { step: "resolve_index_scope", detail: `${indexScope.length} index(es)` },
-            ];
-            if (query.introTargetUserId?.trim() && query.introTargetUserId.trim() === context.userId) {
-                return error("You cannot discover introductions for yourself. Try regular discovery instead.");
-            }
-            const _discoverTraceEmitter = requestContext.getStore()?.traceEmitter;
-            const _discoverGraphStart = Date.now();
-            _discoverTraceEmitter?.({ type: "graph_start", name: "opportunity" });
-            // Chat-driven invocations run under the orchestrator trigger: persist
-            // opens at 'negotiating', negotiate fans out with a 60s park window,
-            // each accepted draft streams via traceEmitter, and the persist step
-            // surfaces already-accepted pairs. Other callers (maintenance, queue
-            // workers) still get the 'ambient' default.
-            // Orchestrator trigger fires for both web chat (has sessionId) and MCP
-            // (isMcp=true, no sessionId). Both are user-initiated discovery that
-            // should persist as `negotiating` and flip to `draft` post-finalize via
-            // onCandidateResolved. Ambient/cron paths leave both falsy and use the
-            // `pending` default.
-            const runDiscoveryOrchestrator = !!context.sessionId || !!context.isMcp;
-            const result = await runDiscoveryFromQuery({
-                opportunityGraph: graphs.opportunity,
-                database,
-                userId: context.userId,
-                query: searchQuery,
-                indexScope,
-                limit: 20,
-                presenter: createOpportunityPresenter(),
-                useHomeCardFormat: true,
-                triggerIntentId,
-                targetUserId: query.targetUserId?.trim() || undefined,
-                onBehalfOfUserId: query.introTargetUserId?.trim() || undefined,
-                cache,
-                // MCP-only: cap the negotiate phase at 20 s so Railway's edge proxy
-                // (which 502s the client at ~57 s) never beats the response. The
-                // remainder finalizes in the background and is fetched on the
-                // user's next list_opportunities call. Removable when IND-274
-                // (negotiation conversation continuation) lands.
-                ...(context.isMcp ? { negotiateTimeoutMs: 20000 } : {}),
-                ...(context.sessionId ? { chatSessionId: context.sessionId } : {}),
-                ...(runDiscoveryOrchestrator && { trigger: 'orchestrator' }),
-                ...(deps.chatSummary && { chatSummary: deps.chatSummary }),
-                ...(deps.questionGenerator && { questionGenerator: deps.questionGenerator }),
-                ...(deps.questionerEnqueue && { questionerEnqueue: deps.questionerEnqueue }),
-                ...(context.scopeType && context.scopeId ? { scopeType: context.scopeType, scopeId: context.scopeId } : {}),
-                ...(deps.negotiationSummary && { negotiationSummary: deps.negotiationSummary }),
-                // Decision questions add an LLM call after the negotiation phase.
-                // Capped at QUESTIONER_DISCOVERY_TIMEOUT_MS (12 s default,
-                // env-overridable; see opportunity.discover.ts). Aborted calls return
-                // no questions but the rest of the discovery payload still ships.
-                // For chat sessions, questions are rendered by the frontend via
-                // streamed events (Slice 4). For MCP, they drive a sequential
-                // elicitation/create flow (Slice 5) — the MCP tool handler awaits the
-                // elicitations before returning the tool result. The per-negotiation
-                // summarizer is similarly capped at NEGOTIATION_SUMMARY_TIMEOUT_MS
-                // (5 s default per negotiation). Gated by QUESTIONER_DISCOVERY_ENABLED
-                // (hierarchical: requires QUESTIONER_ENABLED too).
-                enableQuestions: isDiscoveryQuestionsEnabled() &&
-                    (!!context.sessionId || !!context.isMcp),
-            });
-            // ── Pending question injection ────────────────────────────────────
-            // Look up previously-generated questions relevant to this user's
-            // discovery context and merge them into the result alongside any
-            // inline-generated questions from the current run.
-            const pendingQuestionResult = await mergePendingQuestions({
-                findPendingQuestions: deps.findPendingQuestions,
-                userId: context.userId,
-                sourceType: 'discovery',
-                ...(context.scopeType === 'network' && context.scopeId ? { networkId: context.scopeId } : {}),
-                ...(contextIntentId ? { scopeType: 'intent', scopeId: contextIntentId } : {}),
-                surfacedQuestionIds: new Set(), // Dedup handled at chat.agent level
-            });
-            const pendingQuestions = pendingQuestionResult.questions;
-            const _discoverGraphMs = Date.now() - _discoverGraphStart;
-            _discoverTraceEmitter?.({ type: "graph_end", name: "opportunity", durationMs: _discoverGraphMs });
-            const _discoverGraphTimings = [
-                ..._scopeGraphTimings,
-                { name: 'opportunity', durationMs: _discoverGraphMs, agents: [] },
-            ];
-            const allDebugSteps = [
-                ...toolDebugSteps,
-                ...(result.debugSteps ?? []),
-            ];
-            // Extract negotiation timing from trace (if negotiation ran)
-            const negotiateStep = (result.debugSteps ?? []).find(s => s.step === 'negotiate' && s.data?.durationMs != null);
-            const _allGraphTimings = [
-                ..._discoverGraphTimings,
-                ...(negotiateStep?.data?.durationMs != null
-                    ? [{ name: 'negotiation', durationMs: negotiateStep.data.durationMs, agents: [] }]
-                    : []),
-            ];
-            const isIntroducerFlow = !!query.introTargetUserId?.trim();
-            if (result.createIntentSuggested && result.suggestedIntentDescription && !isIntroducerFlow) {
-                return success({
-                    found: false,
-                    count: 0,
-                    createIntentSuggested: true,
-                    suggestedIntentDescription: result.suggestedIntentDescription,
-                    message: "No matching opportunities found. Call create_intent with the suggested description, then discover_opportunities again.",
-                    summary: "No matches found",
-                    ...(result.pagination ? { pagination: result.pagination } : {}),
-                    debugSteps: allDebugSteps,
-                    _graphTimings: _allGraphTimings,
-                    ...(() => {
-                        const allQ = [...(result.questions ?? []), ...pendingQuestions];
-                        return allQ.length > 0 ? { questions: allQ } : {};
-                    })(),
-                    ...(result.discoveryQuestionsDebug ? { _discoveryQuestionsDebug: result.discoveryQuestionsDebug } : {}),
-                });
-            }
-            if (!result.found) {
-                return success({
-                    found: false,
-                    count: 0,
-                    message: result.message ?? "No matching opportunities found.",
-                    summary: "No matches found",
-                    ...(result.pagination ? { pagination: result.pagination } : {}),
-                    debugSteps: allDebugSteps,
-                    _graphTimings: _allGraphTimings,
-                    ...(() => {
-                        const allQ = [...(result.questions ?? []), ...pendingQuestions];
-                        return allQ.length > 0 ? { questions: allQ } : {};
-                    })(),
-                    ...(result.discoveryQuestionsDebug ? { _discoveryQuestionsDebug: result.discoveryQuestionsDebug } : {}),
-                });
-            }
-            // Found but only existing connections (no new opportunities created)
-            const forMention = result.existingConnectionsForMention ?? result.existingConnections ?? [];
-            if ((result.opportunities?.length ?? 0) === 0 && forMention.length > 0) {
-                return success({
-                    found: true,
-                    count: 0,
-                    message: result.message ??
-                        "No new opportunities created; you already have a connection with: " +
-                            forMention.map((c) => c.name + (c.status ? " (" + c.status + ")" : "")).join(", ") +
-                            ". View on your home page.",
-                    existingConnections: result.existingConnections,
-                    summary: "No new matches (existing connections only)",
-                    debugSteps: allDebugSteps,
-                    _graphTimings: _allGraphTimings,
-                    ...(() => {
-                        const allQ = [...(result.questions ?? []), ...pendingQuestions];
-                        return allQ.length > 0 ? { questions: allQ } : {};
-                    })(),
-                    ...(result.discoveryQuestionsDebug ? { _discoveryQuestionsDebug: result.discoveryQuestionsDebug } : {}),
-                });
-            }
-            // MCP-only: refresh persisted opp statuses from the DB. The graph captures
-            // state.opportunities at persist time, but the negotiate phase mutates each
-            // opp's DB row independently. Without this refresh we'd render persist-time
-            // 'negotiating' as if it were 'draft'. Also drops rejected/stalled — they
-            // are not actionable post-negotiation. Existing-connection cards (cards
-            // whose opportunityId is in result.existingConnections) are preserved as-is
-            // per opportunity.discover.ts's EXISTING_CONNECTION_CARD_STATUSES contract.
-            const existingConnectionIds = new Set((result.existingConnections ?? [])
-                .map((c) => c.opportunityId)
-                .filter((id) => typeof id === 'string'));
-            const candidatesArr = result.opportunities ?? [];
-            let negotiatingCount = 0;
-            let cards = candidatesArr;
-            if (context.isMcp && candidatesArr.length > 0) {
-                const newlyCreatedIds = candidatesArr
-                    .filter((c) => !existingConnectionIds.has(c.opportunityId))
-                    .map((c) => c.opportunityId);
-                const refreshed = newlyCreatedIds.length > 0
-                    ? await database.getOpportunitiesByIds(newlyCreatedIds)
-                    : [];
-                const statusById = new Map(refreshed.map((o) => [o.id, o.status]));
-                const draftCards = [];
-                for (const card of candidatesArr) {
-                    if (existingConnectionIds.has(card.opportunityId)) {
-                        // Re-surfaced opp from a prior run — keep with its discover-time status.
-                        draftCards.push(card);
-                        continue;
-                    }
-                    const refreshedStatus = statusById.get(card.opportunityId);
-                    if (refreshedStatus === 'draft') {
-                        draftCards.push({ ...card, status: refreshedStatus });
-                        continue;
-                    }
-                    if (refreshedStatus === 'negotiating') {
-                        negotiatingCount += 1;
-                        continue;
-                    }
-                    if (refreshedStatus === 'rejected' || refreshedStatus === 'stalled') {
-                        continue; // drop
-                    }
-                    // 'pending' / 'latent' / unknown — not expected post-IND-287. Treat as
-                    // negotiating (count only) and log so we can spot wiring regressions.
-                    discoverOpportunitiesLog.warn('unexpected refreshed status — counting as negotiating', {
-                        opportunityId: card.opportunityId,
-                        refreshedStatus,
-                    });
-                    negotiatingCount += 1;
-                }
-                cards = draftCards;
-            }
-            // Build card data; cap at CHAT_DISPLAY_LIMIT (remaining feeds into pagination)
-            const allCardData = cards.map((opp) => ({
-                opportunityId: opp.opportunityId,
-                userId: opp.userId,
-                name: opp.name,
-                avatar: opp.avatar,
-                mainText: getSafePresentationOrSkip(opp, { counterpartName: opp.name })?.summary ?? "",
-                cta: opp.homeCardPresentation?.suggestedAction,
-                headline: opp.homeCardPresentation?.headline,
-                primaryActionLabel: opp.homeCardPresentation?.primaryActionLabel,
-                secondaryActionLabel: opp.homeCardPresentation?.secondaryActionLabel,
-                mutualIntentsLabel: opp.homeCardPresentation?.mutualIntentsLabel,
-                narratorChip: opp.narratorChip,
-                viewerRole: opp.viewerRole,
-                isGhost: opp.isGhost ?? false,
-                score: opp.score,
-                status: opp.status,
-                ...(opp.secondParty && { secondParty: opp.secondParty }),
-            }));
-            const displayedCards = allCardData.slice(0, CHAT_DISPLAY_LIMIT);
-            const extraFromCap = allCardData.length - displayedCards.length;
-            if (context.isMcp && deps.mintConnectLink) {
-                const mintConnectLink = deps.mintConnectLink;
-                await Promise.all(displayedCards.map(async (card, idx) => {
-                    const source = cards[idx];
-                    await attachActionableLinks(card, {
-                        viewerId: context.userId,
-                        viewerApproved: source?.viewerApproved,
-                        viewerActedAt: source?.viewerActedAt,
-                        counterpartUserId: source?.userId ?? card.userId,
-                        mintConnectLink,
-                        frontendUrl: deps.frontendUrl,
-                        preferredSurface: context.clientSurface,
-                    });
-                }));
-            }
-            let message = buildOpportunityPresentation(displayedCards, {
-                isMcp: context.isMcp ?? false,
-                leadIn: `Found ${displayedCards.length} potential connection(s).`,
-            });
-            const existingForMention = result.existingConnectionsForMention ?? result.existingConnections ?? [];
-            if (existingForMention.length > 0) {
-                message +=
-                    "\n\nYou already have a connection with: " +
-                        existingForMention.map((c) => c.name + (c.status ? " (" + c.status + ")" : "")).join(", ") +
-                        ". View on your home page.";
-            }
-            // Orchestrator-only: dedupAlreadyAccepted surfaces pairs that already
-            // have an accepted opp between the users. Tell the LLM so it can guide
-            // the user to the existing chat instead of treating this like a brand-
-            // new connection.
-            if (result.alreadyAcceptedPairs && result.alreadyAcceptedPairs.length > 0) {
-                message +=
-                    `\n\nYou already have ${result.alreadyAcceptedPairs.length} accepted opportunity(ies) with some of these candidates — open the existing chat with them rather than creating a new draft.`;
-            }
-            const totalRemaining = (result.pagination?.remaining ?? 0) + extraFromCap;
-            if (totalRemaining > 0 && result.pagination?.discoveryId) {
-                message += `\n\nThere are ${totalRemaining} more candidates. Ask if the user wants to see more — they can say "show me more" and you should call discover_opportunities with continueFrom="${result.pagination.discoveryId}".`;
-            }
-            else if (isIntroducerFlow) {
-                message += `\n\nThese are all the introduction candidates I found for this person.`;
-            }
-            else {
-                message += `\n\nThese are all the connections I found. If the user wants to attract more connections, suggest they create a signal — e.g. "Would you like to create a signal so others looking for someone like you can find you?" If they agree, call create_intent with a description based on what they were searching for.`;
-            }
-            // MCP-only: tell the LLM how many opps are still negotiating in the background
-            // and how to fetch them. This is the deferred-surfacing handshake — the user's
-            // next list_opportunities call will pick up the rest as they finalize.
-            if (context.isMcp && negotiatingCount > 0) {
-                if (displayedCards.length > 0) {
-                    message += `\n\n${negotiatingCount} more opportunit${negotiatingCount === 1 ? 'y is' : 'ies are'} still being evaluated — check back via \`list_opportunities\` shortly.`;
-                }
-                else {
-                    // No cards shown. Rebuild the message without the misleading
-                    // "Found 0 potential connection(s)" lead-in but preserve the
-                    // existing-connections mention and already-accepted-pairs note
-                    // appended earlier — those are standalone facts independent of
-                    // any draft cards. Pagination/intro/closing trailers are dropped
-                    // intentionally (they only make sense when cards are shown).
-                    let rebuilt = `Found candidates, but they're still being evaluated. Try \`list_opportunities\` in a minute — ${negotiatingCount} pending.`;
-                    if (existingForMention.length > 0) {
-                        rebuilt +=
-                            "\n\nYou already have a connection with: " +
-                                existingForMention.map((c) => c.name + (c.status ? " (" + c.status + ")" : "")).join(", ") +
-                                ". View on your home page.";
-                    }
-                    if (result.alreadyAcceptedPairs && result.alreadyAcceptedPairs.length > 0) {
-                        rebuilt += `\n\nYou already have ${result.alreadyAcceptedPairs.length} accepted opportunity(ies) with some of these candidates — open the existing chat with them rather than creating a new draft.`;
-                    }
-                    message = rebuilt;
-                }
-            }
-            return success({
-                found: true,
-                count: displayedCards.length,
-                message,
-                summary: `Found ${displayedCards.length} match(es)`,
-                ...(result.existingConnections?.length ? { existingConnections: result.existingConnections } : {}),
-                ...(result.pagination ? { pagination: result.pagination } : {}),
-                debugSteps: allDebugSteps,
-                // Distinct from `createIntentSuggested` (no-results path) intentionally:
-                // `handleCreateIntentCallback` in chat.agent.ts auto-creates for that key.
-                // This flag is for the results-found path where the agent must ask the user first.
-                ...(searchQuery && !query.targetUserId && !isIntroducerFlow
-                    ? {
-                        suggestIntentCreationForVisibility: true,
-                        suggestedIntentDescription: searchQuery,
-                    }
-                    : {}),
-                ...(() => {
-                    const allQ = [...(result.questions ?? []), ...pendingQuestions];
-                    return allQ.length > 0 ? { questions: allQ } : {};
-                })(),
-                ...(result.discoveryQuestionsDebug ? { _discoveryQuestionsDebug: result.discoveryQuestionsDebug } : {}),
-                _graphTimings: _allGraphTimings,
-            });
-        },
-    });
-    const getDiscoveryRun = defineTool({
-        name: "get_discovery_run",
-        description: "Checks the status of an async discovery run started by discover_opportunities in MCP contexts. " +
-            "Poll this tool with the discoveryRunId roughly every 5 seconds until status is succeeded, failed, or cancelled. " +
-            "While status is queued or running, keep polling THIS tool — do NOT call discover_opportunities again (that does not speed anything up and returns the same run). " +
-            "When succeeded, the result field contains the same discovery payload that discover_opportunities would have returned synchronously.",
-        querySchema: z.object({
-            discoveryRunId: z.string().describe("Discovery run ID returned by discover_opportunities."),
-        }),
-        handler: async ({ context, query }) => {
-            if (!deps.discoveryRuns) {
-                return error("Async discovery runs are not available in this context.");
-            }
-            const run = await deps.discoveryRuns.get(query.discoveryRunId, context.userId);
-            if (!run)
-                return error("Discovery run not found.");
-            return success({
-                discoveryRunId: run.id,
-                status: run.status,
-                progress: run.progress ?? null,
-                result: run.result ?? null,
-                error: run.error ?? null,
-                cancelRequestedAt: run.cancelRequestedAt?.toISOString?.() ?? null,
-                createdAt: run.createdAt.toISOString(),
-                startedAt: run.startedAt?.toISOString?.() ?? null,
-                completedAt: run.completedAt?.toISOString?.() ?? null,
-            });
-        },
-    });
-    const cancelDiscoveryRun = defineTool({
-        name: "cancel_discovery_run",
-        description: "Requests cancellation for an async discovery run. If the queued job has not started, it is removed and marked cancelled. " +
-            "If already running, the worker observes cancellation and stops at the next cancellation check.",
-        querySchema: z.object({
-            discoveryRunId: z.string().describe("Discovery run ID returned by discover_opportunities."),
-        }),
-        handler: async ({ context, query }) => {
-            if (!deps.discoveryRuns || !deps.discoveryRunQueue) {
-                return error("Async discovery runs are not available in this context.");
-            }
-            const existing = await deps.discoveryRuns.get(query.discoveryRunId, context.userId);
-            if (!existing)
-                return error("Discovery run not found.");
-            if (!["queued", "running"].includes(existing.status)) {
-                return success({
-                    discoveryRunId: existing.id,
-                    status: existing.status,
-                    cancelled: existing.status === "cancelled",
-                    message: `Discovery run is already ${existing.status}.`,
-                });
-            }
-            const run = await deps.discoveryRuns.requestCancel(query.discoveryRunId, context.userId);
-            if (!run)
-                return error("Discovery run is no longer cancellable.");
-            const removed = await deps.discoveryRunQueue.cancel(run.id);
-            if (removed) {
-                await deps.discoveryRuns.markCancelled(run.id, "cancelled before worker start");
-            }
-            const updated = await deps.discoveryRuns.get(run.id, context.userId);
-            const status = updated?.status ?? (removed ? "cancelled" : run.status);
-            const message = removed
-                ? "Discovery run cancelled."
-                : status === "queued"
-                    ? "Cancellation requested while the discovery run is still queued. It will be skipped or cancelled before work starts."
-                    : status === "running"
-                        ? "Cancellation requested. The running worker will stop at the next cancellation check."
-                        : `Cancellation requested. Discovery run is now ${status}.`;
-            return success({
-                discoveryRunId: run.id,
-                status,
-                cancelled: removed || status === "cancelled",
-                message,
-            });
-        },
-    });
-    const listOpportunities = defineTool({
-        name: "list_opportunities",
-        description: "Lists the authenticated user's actionable opportunities (discovered connections). Returns opportunity cards ready for display.\n\n" +
-            "**What are opportunities?** Matches between users whose intents complement each other within shared networkes. " +
-            "Each opportunity has a status: draft (not yet sent), pending (sent, awaiting response), accepted, rejected, or expired.\n\n" +
-            "**What this returns:** Only draft and pending opportunities — the ones the user can still act on. " +
-            "Accepted, rejected, and expired ones are not surfaced through this tool.\n\n" +
-            "**When to use:** When the user wants to see their current matches or review what's waiting for their response.\n\n" +
-            "**Returns:** Up to 3 opportunity code blocks (interactive cards) with counterpart name, match reasoning, confidence score, " +
-            "and current status. Use update_opportunity to act on them (send, accept, reject).",
-        querySchema: z.object({
-            networkId: z
-                .string()
-                .optional()
-                .describe("Network UUID to filter opportunities to a specific community. Get from read_networks. Defaults to the scoped network in network-scoped chats. Omit to see opportunities across all networks."),
-            scopeType: z
-                .enum(['intent'])
-                .optional()
-                .describe("Optional selected scope type. Use 'intent' to narrow listed opportunities to a selected intent."),
-            scopeId: z
-                .string()
-                .optional()
-                .describe("Selected intent UUID when scopeType is 'intent'. Ignored only when absent."),
-            includeDigestMarkers: z
-                .boolean()
-                .optional()
-                .describe("Internal scheduled-digest mode only. When true, includes hidden delivery markers so the digest send pass can confirm only edited-in opportunities."),
-        }),
-        handler: async ({ context, query }) => {
-            const scopedNetworkId = focusedNetworkId(context) ?? context.networkId?.trim();
-            const scopedIndexLabel = focusedNetworkLabel(context);
-            // Strict scope enforcement: when chat is network-scoped, only allow that index
-            if (scopedNetworkId &&
-                query.networkId?.trim() &&
-                query.networkId.trim() !== scopedNetworkId) {
-                return error(`This chat is scoped to ${scopedIndexLabel}. You can only list opportunities from this community.`);
-            }
-            const effectiveIndexId = (scopedNetworkId || query.networkId?.trim()) ?? undefined;
-            if (effectiveIndexId && !UUID_REGEX.test(effectiveIndexId)) {
-                return error("Invalid network ID format.");
-            }
-            const contextIntentId = focusedIntentId(context);
-            const rawScopeId = query.scopeId?.trim() || undefined;
-            if (query.scopeType === 'intent' && !rawScopeId) {
-                return error("scopeId required when scopeType is intent.");
-            }
-            if (!query.scopeType && rawScopeId) {
-                return error("scopeType=intent required when scopeId is provided.");
-            }
-            if (rawScopeId && !UUID_REGEX.test(rawScopeId)) {
-                return error("Invalid scope ID format.");
-            }
-            if (contextIntentId && rawScopeId && contextIntentId !== rawScopeId) {
-                return error("This chat is scoped to a different intent.");
-            }
-            const effectiveIntentScope = contextIntentId
-                ? { scopeType: 'intent', scopeId: contextIntentId }
-                : query.scopeType === 'intent' && rawScopeId
-                    ? { scopeType: 'intent', scopeId: rawScopeId }
-                    : {};
-            // The MCP/chat surface exposes actionable opportunities.
-            // `latent` is included so the introducer-as-viewer can see their unapproved
-            // connector-flow cards ("do you know someone for X?"). Other latent visibility
-            // rules from isActionableForViewer (latent + no introducer; latent + approved=true
-            // mid-negotiation) are correct at the ACL layer but should not flow through the
-            // chat tool — patient/peer wait for the negotiation to land them in `pending`.
-            const statuses = ["draft", "pending", "latent"];
-            // Fetch wider than CHAT_DISPLAY_LIMIT so selectByComposition has both
-            // buckets to balance — otherwise a category that dominates the natural
-            // sort order can fill the whole window and starve the other section.
-            const fetched = await database.getOpportunitiesForUser(context.userId, {
-                networkId: effectiveIndexId,
-                ...effectiveIntentScope,
-                statuses,
-                limit: CHAT_FETCH_LIMIT,
-            });
-            const skippedIds = [];
-            const buildListDebugSteps = () => {
-                const steps = [];
-                if (skippedIds.length > 0) {
-                    steps.push({
-                        step: "opportunity_display_skips",
-                        detail: `${skippedIds.length} opportunity card(s) couldn't be displayed`,
-                        data: {
-                            skippedCount: skippedIds.length,
-                            totalOpportunities: fetched.length,
-                            skippedOpportunityIds: skippedIds,
-                        },
-                    });
-                }
-                return steps;
-            };
-            const recordCallerMismatch = (opp) => {
-                logger.warn("list_opportunities: skipping opportunity where caller is not an actor", {
-                    opportunityId: opp.id,
-                    viewerId: context.userId,
-                    actorUserIds: opp.actors
-                        .map((a) => a.userId)
-                        .filter((userId) => typeof userId === "string"),
-                });
-                skippedIds.push(opp.id);
-            };
-            // Read invariant: only surface opportunities the caller actually
-            // participates in. Apply before latent filtering, dedup/selection, and
-            // profile/user batch fetches so a mismatched row cannot influence which
-            // valid opportunities are selected or trigger cross-user reads.
-            const callerScoped = fetched.filter((opp) => {
-                if (opp.actors.some((a) => a.userId === context.userId))
-                    return true;
-                recordCallerMismatch(opp);
-                return false;
-            });
-            // Latent rows in chat are introducer-as-viewer only. The ACL layer
-            // (isActionableForViewer) returns true for several other latent cases —
-            // those belong to the home feed, not the digest/ambient surface.
-            const visible = callerScoped.filter((opp) => {
-                if (opp.status !== "latent")
-                    return true;
-                const me = opp.actors.find((a) => a.userId === context.userId);
-                return me?.role === "introducer";
-            });
-            // Deduplicate so each counterpart appears at most once — keeps the
-            // highest-confidence opportunity per person across discovery runs.
-            const deduped = deduplicateByPerson(visible, context.userId);
-            const isDigestMode = context.isMcp === true && query.includeDigestMarkers === true;
-            // ── Digest-mode cross-day suppression ──
-            // Scheduled briefs must not repeat themselves: drop candidates whose
-            // counterpart the user already connected with (accepted opportunity
-            // exists — a re-discovery run re-minting the same person must not
-            // resurface them), drop candidates already shown per the delivery
-            // ledger, and when nothing fresh remains re-show the least-recently
-            // shown candidate past the cooldown, flagged as a redelivery so the
-            // digest can frame it as a reminder. Chat mode is untouched — a user
-            // asking "show my opportunities" should always see them.
-            // Every fetch here is best-effort: a failed read degrades to no
-            // suppression rather than an empty brief.
-            let digestPool = deduped;
-            let redeliveryIds = new Set();
-            if (isDigestMode && deduped.length > 0) {
-                const acceptedCounterpartIds = new Set();
-                try {
-                    // effectiveIntentScope scopes the statuses: ["accepted"] suppression fetch.
-                    const acceptedOpps = await database.getOpportunitiesForUser(context.userId, {
-                        ...(effectiveIndexId ? { networkId: effectiveIndexId } : {}),
-                        ...effectiveIntentScope,
-                        statuses: ["accepted"],
-                        limit: ACCEPTED_SUPPRESSION_FETCH_LIMIT,
-                    });
-                    for (const opp of acceptedOpps) {
-                        for (const actor of opp.actors) {
-                            if (actor.userId && actor.userId !== context.userId && actor.role !== "introducer") {
-                                acceptedCounterpartIds.add(actor.userId);
-                            }
-                        }
-                    }
-                }
-                catch (err) {
-                    logger.warn("digest suppression: failed to fetch accepted opportunities, skipping counterpart suppression", { err });
-                }
-                let deliveredRows = [];
-                if (deps.deliveryLedger?.getDeliveredOpportunities) {
-                    try {
-                        const rows = await deps.deliveryLedger.getDeliveredOpportunities({
-                            userId: context.userId,
-                            opportunityIds: deduped.map((opp) => opp.id),
-                        });
-                        // Defensive Date coercion — ledger rows may cross a serialization boundary.
-                        deliveredRows = rows.map((row) => ({
-                            opportunityId: row.opportunityId,
-                            deliveredAtStatus: row.deliveredAtStatus,
-                            deliveredAt: row.deliveredAt instanceof Date ? row.deliveredAt : new Date(row.deliveredAt),
-                        }));
-                    }
-                    catch (err) {
-                        logger.warn("digest suppression: failed to read delivery ledger, skipping shown-opportunity dedup", { err });
-                    }
-                }
-                const digestSelection = selectDigestCandidates(deduped, {
-                    viewerId: context.userId,
-                    acceptedCounterpartIds,
-                    deliveredRows,
-                });
-                digestPool = digestSelection.pool;
-                redeliveryIds = digestSelection.redeliveryIds;
-            }
-            // Compose-balance across feed categories so the digest/ambient prompt
-            // can fill both Section A (connection) and Section B (connector-flow).
-            // Falls back to the unbalanced view when the helper has nothing to do.
-            const selected = digestPool.length > 0
-                ? selectByComposition(digestPool, context.userId)
-                : digestPool;
-            const opportunities = selected.slice(0, CHAT_DISPLAY_LIMIT);
-            if (!opportunities || opportunities.length === 0) {
-                if (skippedIds.length > 0) {
-                    const listDebugSteps = buildListDebugSteps();
-                    return success({
-                        found: false,
-                        count: 0,
-                        summary: "Some opportunities couldn't be displayed",
-                        message: "I found opportunities, but couldn't render them. Please try again.",
-                        ...(listDebugSteps.length ? { debugSteps: listDebugSteps } : {}),
-                    });
-                }
-                // Digest mode: distinguish "everything was already shown" from "nothing
-                // exists" so the brief omits the people section instead of prompting
-                // the user to run discovery.
-                if (isDigestMode && deduped.length > 0) {
-                    return success({
-                        found: false,
-                        count: 0,
-                        summary: "No new opportunities to show",
-                        message: "No new opportunities today — everything actionable has already been shown recently. Omit the people section from the digest.",
-                    });
-                }
-                return success({
-                    found: false,
-                    count: 0,
-                    summary: "No opportunities yet",
-                    message: "You have no opportunities yet. Use discover_opportunities to find connections.",
-                });
-            }
-            // Batch-fetch profiles and users for all counterpart and introducer userIds to avoid N+1
-            const counterpartUserIds = new Set();
-            const introducerUserIds = new Set();
-            for (const opp of opportunities) {
-                const counterpartActor = opp.actors.find((a) => a.userId !== context.userId && a.role !== "introducer");
-                if (counterpartActor?.userId)
-                    counterpartUserIds.add(counterpartActor.userId);
-                const introducerActor = opp.actors.find((a) => a.role === "introducer" && a.userId !== context.userId);
-                if (introducerActor?.userId)
-                    introducerUserIds.add(introducerActor.userId);
-            }
-            const allUserIds = [
-                ...new Set([...counterpartUserIds, ...introducerUserIds]),
-            ];
-            const [profileResults, userResults] = await Promise.all([
-                Promise.all(allUserIds.map((id) => database.getProfile(id))),
-                Promise.all(allUserIds.map((id) => database.getUser(id))),
-            ]);
-            const profileMap = new Map();
-            const userMap = new Map();
-            allUserIds.forEach((userId, i) => {
-                const profile = profileResults[i] ?? null;
-                const user = userResults[i] ?? null;
-                if (profile)
-                    profileMap.set(userId, profile);
-                if (user)
-                    userMap.set(userId, user);
-            });
-            const cardDataList = [];
-            const seenOpportunityIds = new Set();
-            if (isDigestMode) {
-                // ── Digest mode: use LLM presenter for rich, second-person card text ──
-                const presenter = createOpportunityPresenter();
-                const presenterDb = database;
-                const PRESENTER_CONCURRENCY = 6;
-                for (let i = 0; i < opportunities.length; i += PRESENTER_CONCURRENCY) {
-                    const chunk = opportunities.slice(i, i + PRESENTER_CONCURRENCY);
-                    const chunkCards = await Promise.all(chunk.map(async (opp) => {
-                        if (seenOpportunityIds.has(opp.id))
-                            return null;
-                        seenOpportunityIds.add(opp.id);
-                        try {
-                            const counterpartActor = opp.actors.find((a) => a.userId !== context.userId && a.role !== "introducer");
-                            const counterpartUserId = counterpartActor?.userId;
-                            if (!counterpartUserId)
-                                return null;
-                            const viewerIsIntroducerHere = opp.actors.some((a) => a.role === "introducer" && a.userId === context.userId);
-                            const secondPartyActorForHeadline = viewerIsIntroducerHere
-                                ? opp.actors.find((a) => a.userId !== context.userId &&
-                                    a.userId !== counterpartUserId &&
-                                    a.role !== "introducer")
-                                : undefined;
-                            const introducerActor = opp.actors.find((a) => a.role === "introducer" && a.userId !== context.userId);
-                            const createdByName = opp.detection.createdByName;
-                            const counterpartUser = userMap.get(counterpartUserId) ?? null;
-                            const counterpartName = profileMap.get(counterpartUserId)?.identity?.name ??
-                                counterpartUser?.name ??
-                                "Someone";
-                            const introducerName = createdByName ??
-                                (introducerActor
-                                    ? (profileMap.get(introducerActor.userId)?.identity?.name ?? null)
-                                    : null);
-                            const introducerUser = introducerActor
-                                ? userMap.get(introducerActor.userId) ?? null
-                                : null;
-                            const secondPartyUser = secondPartyActorForHeadline
-                                ? userMap.get(secondPartyActorForHeadline.userId) ?? null
-                                : null;
-                            const secondPartyNameForHeadline = secondPartyActorForHeadline
-                                ? (profileMap.get(secondPartyActorForHeadline.userId)?.identity?.name ??
-                                    secondPartyUser?.name ??
-                                    undefined)
-                                : undefined;
-                            const viewerActor = opp.actors.find((a) => a.userId === context.userId);
-                            const viewerRole = viewerActor?.role ?? "party";
-                            const isCounterpartGhost = counterpartUser?.isGhost ?? false;
-                            try {
-                                // Load the negotiation context alongside presenter context so
-                                // the digest copy can explain *why* the opportunity surfaced
-                                // (EDG-50) — the presenter grounds `digestSummary` in concrete
-                                // negotiation turns when this is present. The same context
-                                // yields the conversationId for the negotiation-trace link
-                                // (EDG-51).
-                                const [ctx, negotiationContext] = await Promise.all([
-                                    gatherOpportunityPresenterContext(presenterDb, opp, context.userId, counterpartUserId),
-                                    loadNegotiationContext(deps.negotiationDatabase, opp.id, opp.status),
-                                ]);
-                                const presentation = await presenter.presentHomeCard({
-                                    ...ctx,
-                                    opportunityStatus: opp.status,
-                                    ...(negotiationContext ? { negotiationContext } : {}),
-                                });
-                                const negotiationUrl = buildNegotiationUrl(negotiationContext?.conversationId, deps.frontendUrl);
-                                // Build narrator chip from presenter output
-                                let narratorChip;
-                                const introducerIsCounterpart = introducerActor && counterpartActor && introducerActor.userId === counterpartActor.userId;
-                                if (introducerActor && introducerActor.userId !== context.userId && !introducerIsCounterpart) {
-                                    const narratorName = introducerName?.trim() || "Someone";
-                                    narratorChip = {
-                                        name: narratorName,
-                                        text: stripLeadingNarratorName(presentation.narratorRemark, narratorName),
-                                        avatar: introducerUser?.avatar ?? null,
-                                        userId: introducerActor.userId,
-                                    };
-                                }
-                                else if (introducerActor?.userId === context.userId) {
-                                    narratorChip = { name: "You", text: presentation.narratorRemark, userId: context.userId };
-                                }
-                                else {
-                                    narratorChip = { name: "Index", text: presentation.narratorRemark };
-                                }
-                                const card = {
-                                    opportunityId: opp.id,
-                                    userId: counterpartUserId,
-                                    name: counterpartName,
-                                    avatar: counterpartUser?.avatar ?? null,
-                                    mainText: stripUuids(presentation.personalizedSummary),
-                                    digestSummary: stripUuids(presentation.digestSummary),
-                                    // Deep-link to the negotiation trace that produced this card
-                                    // (EDG-51). Only present when a negotiation conversation exists.
-                                    ...(negotiationUrl ? { negotiationUrl } : {}),
-                                    cta: presentation.suggestedAction,
-                                    headline: viewerIsIntroducerHere && secondPartyNameForHeadline
-                                        ? `${counterpartName} → ${secondPartyNameForHeadline}`
-                                        : presentation.headline,
-                                    primaryActionLabel: getPrimaryActionLabel(viewerRole),
-                                    secondaryActionLabel: SECONDARY_ACTION_LABEL,
-                                    mutualIntentsLabel: presentation.mutualIntentsLabel,
-                                    narratorChip,
-                                    viewerRole,
-                                    score: typeof opp.interpretation?.confidence === "number"
-                                        ? opp.interpretation.confidence
-                                        : undefined,
-                                    status: opp.status,
-                                    isGhost: isCounterpartGhost,
-                                    ...(redeliveryIds.has(opp.id) ? { redelivery: true } : {}),
-                                    ...(viewerIsIntroducerHere && secondPartyNameForHeadline
-                                        ? {
-                                            secondParty: {
-                                                name: secondPartyNameForHeadline,
-                                                ...(secondPartyUser?.avatar != null ? { avatar: secondPartyUser.avatar } : {}),
-                                                ...(secondPartyActorForHeadline?.userId ? { userId: secondPartyActorForHeadline.userId } : {}),
-                                            },
-                                        }
-                                        : {}),
-                                };
-                                // Attach actionable links for MCP callers
-                                if (context.isMcp && deps.mintConnectLink) {
-                                    const viewerApproved = viewerActor?.role === "introducer" ? viewerActor.approved === true : undefined;
-                                    await attachActionableLinks(card, {
-                                        viewerId: context.userId,
-                                        viewerApproved,
-                                        viewerActedAt: viewerActor?.actedAt ?? null,
-                                        counterpartUserId,
-                                        mintConnectLink: deps.mintConnectLink,
-                                        frontendUrl: deps.frontendUrl,
-                                        preferredSurface: context.clientSurface,
-                                    });
-                                }
-                                return card;
-                            }
-                            catch (presenterErr) {
-                                logger.warn("LLM presenter failed for list_opportunities digest card, skipping raw fallback", {
-                                    opportunityId: opp.id,
-                                    err: presenterErr,
-                                });
-                                // Scheduled digests should only surface OpportunityPresenter-rendered
-                                // copy. The minimal fallback reuses evaluator reasoning, which can
-                                // contain raw narrator phrasing (for example "The discoverer...")
-                                // and is not suitable for AgentVillage morning briefs.
-                                skippedIds.push(opp.id);
-                                return null;
-                            }
-                        }
-                        catch (err) {
-                            logger.warn("Skipping opportunity that failed to build card", {
-                                opportunityId: opp.id,
-                                err,
-                            });
-                            skippedIds.push(opp.id);
-                            return null;
-                        }
-                    }));
-                    for (const card of chunkCards) {
-                        if (card)
-                            cardDataList.push(card);
-                    }
-                }
-            }
-            else {
-                // ── Chat/list mode: use OpportunityPresenter for user-facing card copy ──
-                const presenter = createOpportunityPresenter();
-                const presenterDb = database;
-                const PRESENTER_CONCURRENCY = 6;
-                for (let i = 0; i < opportunities.length; i += PRESENTER_CONCURRENCY) {
-                    const chunk = opportunities.slice(i, i + PRESENTER_CONCURRENCY);
-                    const chunkCards = await Promise.all(chunk.map(async (opp) => {
-                        if (seenOpportunityIds.has(opp.id))
-                            return null;
-                        seenOpportunityIds.add(opp.id);
-                        try {
-                            const counterpartActor = opp.actors.find((a) => a.userId !== context.userId && a.role !== "introducer");
-                            const counterpartUserId = counterpartActor?.userId;
-                            if (!counterpartUserId)
-                                return null;
-                            const viewerIsIntroducerHere = opp.actors.some((a) => a.role === "introducer" && a.userId === context.userId);
-                            const secondPartyActorForHeadline = viewerIsIntroducerHere
-                                ? opp.actors.find((a) => a.userId !== context.userId &&
-                                    a.userId !== counterpartUserId &&
-                                    a.role !== "introducer")
-                                : undefined;
-                            const introducerActor = opp.actors.find((a) => a.role === "introducer" && a.userId !== context.userId);
-                            const createdByName = opp.detection.createdByName;
-                            const counterpartProfile = profileMap.get(counterpartUserId) ?? null;
-                            const counterpartUser = userMap.get(counterpartUserId) ?? null;
-                            const introducerProfile = introducerActor && !createdByName
-                                ? profileMap.get(introducerActor.userId) ?? null
-                                : null;
-                            const counterpartName = counterpartProfile?.identity?.name ??
-                                counterpartUser?.name ??
-                                "Someone";
-                            const introducerName = createdByName ??
-                                (introducerActor ? introducerProfile?.identity?.name ?? null : null);
-                            const introducerUser = introducerActor
-                                ? userMap.get(introducerActor.userId) ?? null
-                                : null;
-                            const secondPartyUser = secondPartyActorForHeadline
-                                ? userMap.get(secondPartyActorForHeadline.userId) ?? null
-                                : null;
-                            const secondPartyNameForHeadline = secondPartyActorForHeadline
-                                ? (profileMap.get(secondPartyActorForHeadline.userId)?.identity?.name ??
-                                    secondPartyUser?.name ??
-                                    undefined)
-                                : undefined;
-                            const viewerActor = opp.actors.find((a) => a.userId === context.userId);
-                            const viewerRole = viewerActor?.role ?? "party";
-                            const isCounterpartGhost = counterpartUser?.isGhost ?? false;
-                            const [ctx, negotiationContext] = await Promise.all([
-                                gatherOpportunityPresenterContext(presenterDb, opp, context.userId, counterpartUserId),
-                                loadNegotiationContext(deps.negotiationDatabase, opp.id, opp.status),
-                            ]);
-                            const presentation = await presenter.presentHomeCard({
-                                ...ctx,
-                                opportunityStatus: opp.status,
-                                ...(negotiationContext ? { negotiationContext } : {}),
-                            });
-                            let narratorChip;
-                            const introducerIsCounterpart = introducerActor && counterpartActor && introducerActor.userId === counterpartActor.userId;
-                            if (introducerActor && introducerActor.userId !== context.userId && !introducerIsCounterpart) {
-                                const narratorName = introducerName?.trim() || "Someone";
-                                narratorChip = {
-                                    name: narratorName,
-                                    text: stripLeadingNarratorName(presentation.narratorRemark, narratorName),
-                                    avatar: introducerUser?.avatar ?? null,
-                                    userId: introducerActor.userId,
-                                };
-                            }
-                            else if (introducerActor?.userId === context.userId) {
-                                narratorChip = { name: "You", text: presentation.narratorRemark, userId: context.userId };
-                            }
-                            else {
-                                narratorChip = { name: "Index", text: presentation.narratorRemark };
-                            }
-                            const cardData = {
-                                opportunityId: opp.id,
-                                userId: counterpartUserId,
-                                name: counterpartName,
-                                avatar: counterpartUser?.avatar ?? null,
-                                mainText: stripUuids(presentation.personalizedSummary),
-                                cta: presentation.suggestedAction,
-                                headline: viewerIsIntroducerHere && secondPartyNameForHeadline
-                                    ? `${counterpartName} → ${secondPartyNameForHeadline}`
-                                    : presentation.headline,
-                                primaryActionLabel: getPrimaryActionLabel(viewerRole),
-                                secondaryActionLabel: SECONDARY_ACTION_LABEL,
-                                mutualIntentsLabel: presentation.mutualIntentsLabel,
-                                narratorChip,
-                                viewerRole,
-                                score: typeof opp.interpretation?.confidence === "number"
-                                    ? opp.interpretation.confidence
-                                    : undefined,
-                                status: opp.status,
-                                isGhost: isCounterpartGhost,
-                                ...(viewerIsIntroducerHere && secondPartyNameForHeadline
-                                    ? {
-                                        secondParty: {
-                                            name: secondPartyNameForHeadline,
-                                            ...(secondPartyUser?.avatar != null ? { avatar: secondPartyUser.avatar } : {}),
-                                            ...(secondPartyActorForHeadline?.userId ? { userId: secondPartyActorForHeadline.userId } : {}),
-                                        },
-                                    }
-                                    : {}),
-                            };
-                            // For MCP callers (e.g. Edge Claw), mint a connect token and attach
-                            // acceptUrl + profileUrl when the (status, viewerRole) is actionable
-                            // for the viewer. Non-actionable combos (sender-on-draft,
-                            // pending-on-introducer-waiting, rejected, etc.) deliberately get
-                            // no link — the LLM would otherwise hallucinate `/api/.../connect`
-                            // URLs from the exposed opportunityId.
-                            if (context.isMcp && deps.mintConnectLink) {
-                                const viewerApproved = viewerActor?.role === "introducer" ? viewerActor.approved === true : undefined;
-                                await attachActionableLinks(cardData, {
-                                    viewerId: context.userId,
-                                    viewerApproved,
-                                    viewerActedAt: viewerActor?.actedAt ?? null,
-                                    counterpartUserId,
-                                    mintConnectLink: deps.mintConnectLink,
-                                    frontendUrl: deps.frontendUrl,
-                                    preferredSurface: context.clientSurface,
-                                });
-                            }
-                            return cardData;
-                        }
-                        catch (err) {
-                            logger.warn("Skipping opportunity that failed to build presenter card", {
-                                opportunityId: opp.id,
-                                err,
-                            });
-                            skippedIds.push(opp.id);
-                            return null;
-                        }
-                    }));
-                    for (const card of chunkCards) {
-                        if (card)
-                            cardDataList.push(card);
-                    }
-                }
-            }
-            const listDebugSteps = buildListDebugSteps();
-            if (cardDataList.length === 0) {
-                if (skippedIds.length > 0) {
-                    return success({
-                        found: false,
-                        count: 0,
-                        summary: "Some opportunities couldn't be displayed",
-                        message: "I found opportunities, but couldn't render them. Please try again.",
-                        ...(listDebugSteps.length ? { debugSteps: listDebugSteps } : {}),
-                    });
-                }
-                return success({
-                    found: false,
-                    count: 0,
-                    summary: "No opportunities yet",
-                    message: "You have no opportunities yet. Use discover_opportunities to find connections.",
-                });
-            }
-            return success({
-                found: true,
-                count: cardDataList.length,
-                summary: `You have ${cardDataList.length} opportunity(ies)`,
-                message: buildOpportunityPresentation(cardDataList, {
-                    isMcp: context.isMcp ?? false,
-                    leadIn: `You have ${cardDataList.length} opportunity(ies).`,
-                    includeDigestMarkers: context.isMcp === true && query.includeDigestMarkers === true,
-                }),
-                ...(listDebugSteps.length ? { debugSteps: listDebugSteps } : {}),
-            });
-        },
-    });
-    const updateOpportunity = defineTool({
-        name: "update_opportunity",
-        description: "Updates an opportunity's status, advancing it through the connection lifecycle.\n\n" +
-            "**Status transitions:**\n" +
-            "- `pending`: Sends a draft opportunity to the other party. They'll be notified and can accept or reject. " +
-            "This is the primary action after discover_opportunities returns a draft.\n" +
-            "- `accepted`: Accept a received opportunity — opens a direct conversation between both parties. Returns a conversationId to surface to the user.\n" +
-            "- `rejected`: Decline a received opportunity.\n" +
-            "- `expired`: Mark as expired (typically done by the system after timeout).\n\n" +
-            "**When to use:** After discover_opportunities or list_opportunities returns opportunity cards. " +
-            "The user clicks 'Send' (pending), 'Accept', or 'Reject' on the card, and the agent calls this tool. " +
-            "An accepted transition may first return a non-success uptake advisory with preparatory questions. Surface those questions, then retry with all returned question ids in acknowledgedUptakeQuestionIds; acknowledgement confirms presentation, not an answer.\n\n" +
-            "**Returns:** Confirmation with the new status and notification details (who was notified), or a structured uptake advisory without mutation.",
-        querySchema: z.object({
-            opportunityId: z
-                .string()
-                .describe("The UUID of the opportunity to update. Get from discover_opportunities or list_opportunities results."),
-            status: z
-                .enum(["pending", "accepted", "rejected", "expired"])
-                .describe("New status: 'pending' = send the draft to the other party, 'accepted' = accept the connection, " +
-                "'rejected' = decline, 'expired' = mark as timed out."),
-            acknowledgedUptakeQuestionIds: z
-                .array(z.string().min(1))
-                .optional()
-                .describe("On an acknowledged retry after an uptake advisory, include every question id returned by that advisory."),
-            scopeType: z
-                .enum(['intent'])
-                .optional()
-                .describe("Optional selected scope type. Use 'intent' to require this opportunity to belong to a selected intent."),
-            scopeId: z
-                .string()
-                .optional()
-                .describe("Selected intent UUID when scopeType is 'intent'. Must match the chat's focused intent when one exists."),
-        }),
-        handler: async ({ context, query }) => {
-            const opportunityId = query.opportunityId?.trim();
-            if (!opportunityId || !UUID_REGEX.test(opportunityId)) {
-                return error("Valid opportunityId required.");
-            }
-            const contextIntentId = focusedIntentId(context);
-            const rawScopeId = query.scopeId?.trim() || undefined;
-            if (query.scopeType === 'intent' && !rawScopeId) {
-                return error("scopeId required when scopeType is intent.");
-            }
-            if (!query.scopeType && rawScopeId) {
-                return error("scopeType=intent required when scopeId is provided.");
-            }
-            if (rawScopeId && !UUID_REGEX.test(rawScopeId)) {
-                return error("Invalid scope ID format.");
-            }
-            if (contextIntentId && rawScopeId && contextIntentId !== rawScopeId) {
-                return error("This chat is scoped to a different intent.");
-            }
-            const effectiveIntentScope = contextIntentId
-                ? { scopeType: 'intent', scopeId: contextIntentId }
-                : query.scopeType === 'intent' && rawScopeId
-                    ? { scopeType: 'intent', scopeId: rawScopeId }
-                    : {};
-            // Always fetch the opportunity — needed for actor guard and state machine
-            const opportunity = await systemDb.getOpportunity(opportunityId);
-            if (!opportunity) {
-                return error("Opportunity not found.");
-            }
-            // Actor guard: caller must be a party to the opportunity
-            const isActor = opportunity.actors?.some((a) => a.userId === context.userId);
-            if (!isActor) {
-                return error("Opportunity not found.");
-            }
-            // Terminal-state and in-flight-negotiation guard.
-            // Not a full state-machine: the Zod enum already constrains the target status,
-            // and source statuses like `draft` / `latent` remain permitted.
-            if (UPDATE_OPPORTUNITY_BLOCKED_STATUSES.has(opportunity.status)) {
-                return error(`This opportunity is already ${opportunity.status} and cannot be updated.`);
-            }
-            // Strict scope enforcement: when chat is network-scoped, the caller's own
-            // actor entry on this opportunity must be anchored on the bound network.
-            // Mirrors the per-actor filter in getOpportunitiesForUser — relying on
-            // a focus-scope id or any-actor matches would let a counterpart's network
-            // presence shadow a viewer whose own actor is elsewhere.
-            const scopedNetworkId = focusedNetworkId(context) ?? context.networkId?.trim();
-            if (scopedNetworkId) {
-                const callerOnBoundNetwork = opportunity.actors?.some((a) => a.userId === context.userId && a.networkId === scopedNetworkId);
-                if (!callerOnBoundNetwork) {
-                    return error("Opportunity not found.");
-                }
-            }
-            if (!matchesSelectedIntentScope(opportunity, context.userId, effectiveIntentScope)) {
-                return error("Opportunity not found.");
-            }
-            // The caller actor's own network is the exact question lookup boundary,
-            // even for an otherwise unscoped request. A focused network may only be
-            // equal to this after the guard above.
-            // Unscoped callers query all of their exact opportunity questions; a
-            // network-scoped caller is clamped to the bound network. Selecting the
-            // first duplicate actor row would miss a valid question on another
-            // shared network.
-            const uptakeNetworkId = scopedNetworkId;
-            // Soft uptake interlock: only acceptance is advisory-gated. All existing
-            // actor/scope/privacy guards run first so the question lookup cannot be
-            // used to probe opportunities or networks the caller cannot access.
-            if (query.status === "accepted" && isUptakeGuardEnabled() && deps.findPendingQuestions) {
-                try {
-                    const pending = await deps.findPendingQuestions(context.userId, {
-                        sourceType: "opportunity",
-                        sourceId: opportunityId,
-                        modes: ["negotiation"],
-                        purpose: "uptake",
-                        ...(uptakeNetworkId ? { networkId: uptakeNetworkId } : {}),
-                    });
-                    // Defense in depth if a host overlooks one or more filters. Actor
-                    // internals are checked here and never serialized into the advisory.
-                    const exactPending = pending.filter((question) => {
-                        if (question.sourceType !== "opportunity" ||
-                            question.sourceId !== opportunityId ||
-                            question.mode !== "negotiation" ||
-                            question.purpose !== "uptake") {
-                            return false;
-                        }
-                        if (!question.actors?.some((actor) => actor.userId === context.userId))
-                            return false;
-                        if (uptakeNetworkId && !question.actors.some((actor) => actor.userId === context.userId && actor.networkId === uptakeNetworkId)) {
-                            return false;
-                        }
-                        return true;
-                    });
-                    const acknowledged = new Set(query.acknowledgedUptakeQuestionIds ?? []);
-                    if (exactPending.some((question) => !acknowledged.has(question.id))) {
-                        return uptakeAdvisory(opportunityId, exactPending.map(publicUptakeQuestion));
-                    }
-                }
-                catch (err) {
-                    logger.warn("update_opportunity: uptake question lookup failed open", {
-                        opportunityId,
-                        userId: context.userId,
-                        error: err instanceof Error ? err.message : String(err),
-                    });
-                    deps.reportToolError?.(err, {
-                        subsystem: "opportunity",
-                        operation: "opportunity.uptake_lookup",
-                        toolName: "update_opportunity",
-                        userId: context.userId,
-                    });
-                }
-            }
-            const isSend = query.status === "pending";
-            const _updateGraphStart = Date.now();
-            const _updateTraceEmitter = requestContext.getStore()?.traceEmitter;
-            _updateTraceEmitter?.({ type: "graph_start", name: "opportunity" });
-            const result = await invokeWithAbortSignal(graphs.opportunity, {
-                userId: context.userId,
-                operationMode: isSend ? "send" : "update",
-                opportunityId: query.opportunityId,
-                ...(isSend ? {} : { newStatus: query.status }),
-            });
-            const _updateGraphMs = Date.now() - _updateGraphStart;
-            _updateTraceEmitter?.({ type: "graph_end", name: "opportunity", durationMs: _updateGraphMs });
-            if (result.mutationResult) {
-                if (result.mutationResult.success) {
-                    return success({
-                        opportunityId: result.mutationResult.opportunityId,
-                        status: query.status,
-                        message: result.mutationResult.message,
-                        ...(result.mutationResult.notified && { notified: result.mutationResult.notified }),
-                        ...(result.mutationResult.conversationId && {
-                            conversationId: result.mutationResult.conversationId,
-                        }),
-                        _graphTimings: [{ name: 'opportunity', durationMs: _updateGraphMs, agents: result.agentTimings ?? [] }],
-                    });
-                }
-                return error(result.mutationResult.error || "Failed to update opportunity.");
-            }
-            return error("Failed to update opportunity.");
-        },
-    });
-    const confirmOpportunityDelivery = defineTool({
-        name: "confirm_opportunity_delivery",
-        description: "Marks an opportunity as delivered to the user via the OpenClaw channel. " +
-            "Call this for each opportunity you decide to surface, BEFORE including it in your delivery message. " +
-            "The 'trigger' argument records which dispatch path produced this delivery: " +
-            "'ambient' for real-time critical alerts (target ≤3/day), 'digest' for the daily sweep, " +
-            "'accepted' for accepted-opportunity notifications to the counterparty. " +
-            "Idempotent — safe to call even if the opportunity was already confirmed.",
-        querySchema: z.object({
-            opportunityId: z
-                .string()
-                .describe("The UUID of the opportunity to mark as delivered."),
-            trigger: z
-                .enum(['ambient', 'digest', 'accepted'])
-                .describe("Which dispatch path produced this delivery. Use 'ambient' if the dispatch prompt says you are in the ambient pass; use 'digest' if it says you are in the daily digest; use 'accepted' for accepted-opportunity notifications to the counterparty."),
-        }),
-        handler: async ({ context, query }) => {
-            if (!context.isMcp || !context.agentId) {
-                return confirmDeliveryError("unauthenticated", false, "confirm_opportunity_delivery is only available to authenticated agent MCP contexts.");
-            }
-            if (!deps.deliveryLedger) {
-                return confirmDeliveryError("ledger_unavailable", false, "Delivery ledger not available in this context.");
-            }
-            if (!UUID_REGEX.test(query.opportunityId)) {
-                return confirmDeliveryError("invalid_opportunity_id", false, "Invalid opportunity ID format.");
-            }
-            try {
-                const result = await deps.deliveryLedger.confirmOpportunityDelivery({
-                    opportunityId: query.opportunityId,
-                    userId: context.userId,
-                    agentId: context.agentId,
-                    trigger: query.trigger,
-                });
-                return success({ status: result });
-            }
-            catch (err) {
-                const reason = err instanceof Error ? err.message : String(err);
-                // Permanent failures — the caller MUST NOT retry. Retrying a deleted
-                // opportunity or an unauthorized actor never succeeds and only spams
-                // the ledger / MCP transport.
-                if (reason === 'opportunity_not_found') {
-                    logger.warn('confirm_opportunity_delivery: opportunity not found', {
-                        opportunityId: query.opportunityId,
-                    });
-                    return confirmDeliveryError('opportunity_not_found', false, 'Opportunity not found — it may have been deleted. Do not retry.');
-                }
-                if (reason === 'not_authorized') {
-                    logger.warn('confirm_opportunity_delivery: caller is not an actor', {
-                        opportunityId: query.opportunityId,
-                        userId: context.userId,
-                    });
-                    return confirmDeliveryError('not_authorized', false, 'You are not an actor on this opportunity. Do not retry.');
-                }
-                // Unknown / transient (e.g. DB connectivity) — safe to retry. The
-                // ledger write is idempotent, so a retry that races a prior success
-                // returns 'already_delivered' rather than a duplicate row.
-                logger.error('Failed to confirm opportunity delivery', { err });
-                return confirmDeliveryError('confirm_failed', true, 'Failed to confirm opportunity delivery — transient error, safe to retry.');
-            }
-        },
-    });
-    return [
-        discoverOpportunities,
-        getDiscoveryRun,
-        cancelDiscoveryRun,
-        listOpportunities,
-        updateOpportunity,
-        confirmOpportunityDelivery,
-    ];
-}
-//# sourceMappingURL=opportunity.tools.js.map
+export * from "./application/opportunity.tools.js";