@indexnetwork/protocol 14.3.2-rc.477.1 → 17.0.0-rc.479.1

package/dist/opportunities/application/opportunity.tools.js

@@ -1,720 +1,31 @@
+/**
+ * The opportunity tool registry: list, update, and delivery confirmation.
+ *
+ * `list_opportunities` lives in `opportunity.tools.list.ts` and the shared card
+ * and link helpers in `opportunity.tools.cards.ts`; this file wires the three
+ * tools together and owns the two mutation tools.
+ */
 import { z } from "zod";
 import { requestContext } from "../../shared/observability/request-context.js";
 import { success, error, UUID_REGEX } from "../../shared/agent/tool.helpers.js";
-import { focusedIntentId, focusedNetworkId, focusedNetworkLabel } from "../../shared/agent/tool.scope.js";
-import { MINIMAL_MAIN_TEXT_MAX_CHARS, getPrimaryActionLabel, SECONDARY_ACTION_LABEL } from "../domain/opportunity.labels.js";
-import { narratorRemarkFromReasoning, stripUuids } from "../domain/opportunity.presentation.js";
-import { safeFallbackSummary } from "../domain/opportunity.safe-presentation.js";
-import { buildOpportunityPresentation } from "./opportunity.card-presentation.js";
+import { focusedIntentId, focusedNetworkId } from "../../shared/agent/tool.scope.js";
+import { OpportunityPresenter, gatherPresenterContext } from "./opportunity.presentation.js";
 import { isUptakeGuardEnabled } from "../../questions/index.js";
-import { OpportunityPresenter, gatherPresenterContext } from "./opportunity.presenter.js";
-import { loadNegotiationContext } from "./negotiation-context.loader.js";
 import { admitOpportunityUpdate } from './opportunity.update-admission.js';
 import { opportunityOwnerActionForStatus } from './opportunity.owner-approval.js';
 import { ownerApprovalProvenanceFor } from './opportunity.owner-provenance.js';
-import { selectOpportunityFeed } from './opportunity.feed-selection.js';
-export { buildOpportunityPresentation } from "./opportunity.card-presentation.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 { invokeWithAbortSignal } from "../../shared/agent/model-signal.js";
-const logger = protocolLogger("ChatTools:Opportunity");
-/**
- * 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.
-    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`;
-}
-/**
- * Build the agent-facing deep link for an opportunity — the canonical
- * `https://index.network/o/<id>` universal link. Returns `undefined` when
- * `frontendUrl` is unset or there is no opportunity id.
- *
- * This is the *only* place the protocol mints an opportunity deep link. It is
- * a navigation link, not an authority: opening it raises the opportunity card
- * in the Index macOS app when installed and a static Index landing page
- * otherwise. Acceptance stays an authenticated call.
- *
- * No `?link_preview=false` hint here (unlike `buildProfileUrl`): the Hermes
- * plugin mints the identical bare form for payloads the protocol does not
- * touch, and keeping the two byte-identical is what makes its never-overwrite
- * rule invisible.
- */
-export function buildOpportunityAppUrl(opportunityId, frontendUrl) {
-    if (!frontendUrl || !opportunityId)
-        return undefined;
-    const base = frontendUrl.replace(/\/+$/, "");
-    return `${base}/o/${opportunityId}`;
-}
-/**
- * Attach the agent-facing profile link for a counterpart to `card` (mutates
- * in place). Every counterpart has a profile page worth linking to — without
- * this, the agent gets a name with no URL attached and tends to fabricate
- * one. Accept/act guidance is plain text ("accept in the Index app"); no
- * actionable URLs are minted here.
- */
-export function attachProfileLink(card, opts) {
-    const profileUrl = buildProfileUrl(opts.counterpartUserId, opts.frontendUrl);
-    if (profileUrl)
-        card.profileUrl = profileUrl;
-}
-/**
- * Attach the opportunity deep link to `card` (mutates in place) so every MCP
- * client — Claude Desktop, the CLI, the web, Hermes — can hand the user one
- * clickable link to the card instead of fabricating one from an id.
- */
-export function attachOpportunityAppLink(card, opts) {
-    const appUrl = buildOpportunityAppUrl(card.opportunityId, opts.frontendUrl);
-    if (appUrl)
-        card.appUrl = appUrl;
-}
-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),
-        },
-    });
-}
-/**
- * IND-593: stable fail-closed denial for the owner-approval boundary. The
- * `missing` reason carries the fresh, server-derived interaction challenge the
- * owner must explicitly approve; all other reasons carry no challenge.
- */
-function ownerApprovalDenial(opportunityId, action, verdict) {
-    return JSON.stringify({
-        success: false,
-        error: `Owner approval required for this opportunity ${action} (${verdict.reason}).`,
-        approval: {
-            code: "owner_approval_required",
-            reason: verdict.reason,
-            opportunityId,
-            action,
-            ...(verdict.challenge
-                ? { interactionId: verdict.challenge.interactionId, expiresAt: verdict.challenge.expiresAt }
-                : {}),
-        },
-    });
-}
-/**
- * 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;
-/**
- * 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.presentCard()
- * 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 } : {}),
-                },
-            }
-            : {}),
-    };
-}
-function confirmDeliveryError(code, retryable, message) {
-    return JSON.stringify({ success: false, error: message, code, retryable });
-}
+export { buildOpportunityPresentation } from "./opportunity.presentation.js";
+import { sendOpportunity, updateOpportunityStatus } from "./opportunity.graph.modes.js";
+import { createListOpportunitiesTool } from "./opportunity.tools.list.js";
+import { confirmDeliveryError, logger, ownerApprovalDenial, publicUptakeQuestion, uptakeAdvisory } from "./opportunity.tools.cards.js";
+export { attachOpportunityAppLink, attachProfileLink, buildMinimalOpportunityCard, buildNegotiationUrl, buildOpportunityAppUrl, buildProfileUrl } from "./opportunity.tools.cards.js";
 export function createOpportunityTools(defineTool, deps) {
     const { database, userDb, systemDb, graphs, cache } = deps;
     const createOpportunityPresenter = deps.opportunityPresentation?.createPresenter ??
         (() => new OpportunityPresenter());
     const gatherOpportunityPresenterContext = deps.opportunityPresentation?.gatherPresenterContext ??
         gatherPresenterContext;
-    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 }
-                    : {};
-            const selection = await selectOpportunityFeed({
-                reader: database,
-                deliveryLedger: deps.deliveryLedger,
-                viewerId: context.userId,
-                networkId: effectiveIndexId,
-                intentScope: effectiveIntentScope,
-                isMcp: context.isMcp === true,
-                includeDigestMarkers: query.includeDigestMarkers,
-                displayLimit: CHAT_DISPLAY_LIMIT,
-                warn: (message, data) => logger.warn(message, data),
-            });
-            const { opportunities, dedupedCount, skippedIds, redeliveryIds, fetchedCount, isDigestMode } = selection;
-            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: fetchedCount,
-                            skippedOpportunityIds: skippedIds,
-                        },
-                    });
-                }
-                return steps;
-            };
-            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 && dedupedCount > 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. Create or refine an approved signal with create_intent or update_intent; matches are created in the background. Use list_opportunities later to review persisted results.",
-                });
-            }
-            // 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.presentCard({
-                                    ...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 the agent-facing profile and opportunity links for
-                                // MCP callers
-                                if (context.isMcp) {
-                                    attachProfileLink(card, {
-                                        counterpartUserId,
-                                        frontendUrl: deps.frontendUrl,
-                                    });
-                                    attachOpportunityAppLink(card, {
-                                        frontendUrl: deps.frontendUrl,
-                                    });
-                                }
-                                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.presentCard({
-                                ...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, attach the agent-facing profile link and the
-                            // opportunity deep link so the agent never has to fabricate
-                            // either. Accepting still happens in the Index app behind an
-                            // authenticated call — the deep link only opens the card.
-                            if (context.isMcp) {
-                                attachProfileLink(cardData, {
-                                    counterpartUserId,
-                                    frontendUrl: deps.frontendUrl,
-                                });
-                                attachOpportunityAppLink(cardData, {
-                                    frontendUrl: deps.frontendUrl,
-                                });
-                            }
-                            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. Create or refine an approved signal with create_intent or update_intent; matches are created in the background. Use list_opportunities later to review persisted results.",
-                });
-            }
-            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 listOpportunities = createListOpportunitiesTool(defineTool, deps);
     const updateOpportunity = defineTool({
         name: "update_opportunity",
         description: "Updates an opportunity's status, advancing it through the connection lifecycle.\n\n" +
@@ -885,12 +196,17 @@ export function createOpportunityTools(defineTool, deps) {
             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 operations = deps.opportunityOperations ?? { sendOpportunity, updateOpportunityStatus };
+            const result = isSend
+                ? await operations.sendOpportunity(deps, {
+                    userId: context.userId,
+                    opportunityId: query.opportunityId,
+                })
+                : await operations.updateOpportunityStatus(deps, {
+                    userId: context.userId,
+                    opportunityId: query.opportunityId,
+                    newStatus: query.status,
+                });
             const _updateGraphMs = Date.now() - _updateGraphStart;
             _updateTraceEmitter?.({ type: "graph_end", name: "opportunity", durationMs: _updateGraphMs });
             if (result.mutationResult) {
@@ -903,7 +219,8 @@ export function createOpportunityTools(defineTool, deps) {
                         ...(result.mutationResult.conversationId && {
                             conversationId: result.mutationResult.conversationId,
                         }),
-                        _graphTimings: [{ name: 'opportunity', durationMs: _updateGraphMs, agents: result.agentTimings ?? [] }],
+                        // Neither update nor send invokes an agent, so this stage never reports sub-agent timings.
+                        _graphTimings: [{ name: 'opportunity', durationMs: _updateGraphMs, agents: [] }],
                     });
                 }
                 return error(result.mutationResult.error || "Failed to update opportunity.");