@indexnetwork/protocol 6.14.0-rc.406.1 → 8.0.1-rc.417.1

package/dist/opportunity/application/opportunity.graph.d.ts

@@ -125,11 +125,6 @@ export declare class OpportunityGraphFactory {
         targetUserId: Id<"users"> | undefined;
         onBehalfOfUserId: Id<"users"> | undefined;
         options: import("../domain/opportunity.state.js").OpportunityGraphOptions;
-        trigger: import("../domain/opportunity.state.js").OpportunityTrigger;
-        dedupAlreadyAccepted: {
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[];
         operationMode: "delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing";
         introductionEntities: EvaluatorEntity[];
         introductionHint: string | undefined;
@@ -239,14 +234,6 @@ export declare class OpportunityGraphFactory {
         targetUserId?: Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined;
         onBehalfOfUserId?: Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined;
         options?: import("../domain/opportunity.state.js").OpportunityGraphOptions | import("@langchain/langgraph").OverwriteValue<import("../domain/opportunity.state.js").OpportunityGraphOptions> | undefined;
-        trigger?: import("../domain/opportunity.state.js").OpportunityTrigger | import("@langchain/langgraph").OverwriteValue<import("../domain/opportunity.state.js").OpportunityTrigger> | undefined;
-        dedupAlreadyAccepted?: {
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[] | import("@langchain/langgraph").OverwriteValue<{
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[]> | undefined;
         operationMode?: "delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing" | import("@langchain/langgraph").OverwriteValue<"delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing"> | undefined;
         introductionEntities?: EvaluatorEntity[] | import("@langchain/langgraph").OverwriteValue<EvaluatorEntity[]> | undefined;
         introductionHint?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
@@ -420,17 +407,6 @@ export declare class OpportunityGraphFactory {
         targetUserId: import("@langchain/langgraph").BaseChannel<Id<"users"> | undefined, Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined, unknown>;
         onBehalfOfUserId: import("@langchain/langgraph").BaseChannel<Id<"users"> | undefined, Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined, unknown>;
         options: import("@langchain/langgraph").BaseChannel<import("../domain/opportunity.state.js").OpportunityGraphOptions, import("../domain/opportunity.state.js").OpportunityGraphOptions | import("@langchain/langgraph").OverwriteValue<import("../domain/opportunity.state.js").OpportunityGraphOptions>, unknown>;
-        trigger: import("@langchain/langgraph").BaseChannel<import("../domain/opportunity.state.js").OpportunityTrigger, import("../domain/opportunity.state.js").OpportunityTrigger | import("@langchain/langgraph").OverwriteValue<import("../domain/opportunity.state.js").OpportunityTrigger>, unknown>;
-        dedupAlreadyAccepted: import("@langchain/langgraph").BaseChannel<{
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[], {
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[] | import("@langchain/langgraph").OverwriteValue<{
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[]>, unknown>;
         operationMode: import("@langchain/langgraph").BaseChannel<"delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing", "delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing" | import("@langchain/langgraph").OverwriteValue<"delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing">, unknown>;
         introductionEntities: import("@langchain/langgraph").BaseChannel<EvaluatorEntity[], EvaluatorEntity[] | import("@langchain/langgraph").OverwriteValue<EvaluatorEntity[]>, unknown>;
         introductionHint: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
@@ -668,17 +644,6 @@ export declare class OpportunityGraphFactory {
         targetUserId: import("@langchain/langgraph").BaseChannel<Id<"users"> | undefined, Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined, unknown>;
         onBehalfOfUserId: import("@langchain/langgraph").BaseChannel<Id<"users"> | undefined, Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined, unknown>;
         options: import("@langchain/langgraph").BaseChannel<import("../domain/opportunity.state.js").OpportunityGraphOptions, import("../domain/opportunity.state.js").OpportunityGraphOptions | import("@langchain/langgraph").OverwriteValue<import("../domain/opportunity.state.js").OpportunityGraphOptions>, unknown>;
-        trigger: import("@langchain/langgraph").BaseChannel<import("../domain/opportunity.state.js").OpportunityTrigger, import("../domain/opportunity.state.js").OpportunityTrigger | import("@langchain/langgraph").OverwriteValue<import("../domain/opportunity.state.js").OpportunityTrigger>, unknown>;
-        dedupAlreadyAccepted: import("@langchain/langgraph").BaseChannel<{
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[], {
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[] | import("@langchain/langgraph").OverwriteValue<{
-            opportunityId: string;
-            counterpartyUserId: string;
-        }[]>, unknown>;
         operationMode: import("@langchain/langgraph").BaseChannel<"delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing", "delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing" | import("@langchain/langgraph").OverwriteValue<"delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing">, unknown>;
         introductionEntities: import("@langchain/langgraph").BaseChannel<EvaluatorEntity[], EvaluatorEntity[] | import("@langchain/langgraph").OverwriteValue<EvaluatorEntity[]>, unknown>;
         introductionHint: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
@@ -1220,14 +1185,12 @@ export declare class OpportunityGraphFactory {
                 finalAtomicConflictCount: number;
             };
             existingBetweenActors?: undefined;
-            dedupAlreadyAccepted?: undefined;
             trace?: undefined;
             error?: undefined;
         } | {
             opportunities: never[];
             persistenceOutcome?: undefined;
             existingBetweenActors?: undefined;
-            dedupAlreadyAccepted?: undefined;
             trace?: undefined;
             error?: undefined;
         } | {
@@ -1240,10 +1203,6 @@ export declare class OpportunityGraphFactory {
                 reason?: "same_trigger_recent_duplicate" | "pair_active_negotiation" | "final_atomic_conflict";
                 existingTriggerIntentId?: string;
             }[];
-            dedupAlreadyAccepted: {
-                opportunityId: string;
-                counterpartyUserId: string;
-            }[];
             persistenceOutcome: {
                 evaluatedCount: number;
                 createdCount: number;
@@ -1260,7 +1219,6 @@ export declare class OpportunityGraphFactory {
                     created: number;
                     reactivated: number;
                     existingSkipped: number;
-                    alreadyAccepted: number;
                     totalOutput: number;
                     persistenceOutcome: {
                         evaluatedCount: number;
@@ -1287,7 +1245,6 @@ export declare class OpportunityGraphFactory {
                 };
             }[];
             persistenceOutcome?: undefined;
-            dedupAlreadyAccepted?: undefined;
         };
         read: {
             readResult: {

package/dist/opportunity/application/opportunity.graph.js

@@ -13,7 +13,6 @@
  */
 import { StateGraph, START, END } from '@langchain/langgraph';
 import { OpportunityGraphState } from '../domain/opportunity.state.js';
-import { resolveInitialStatus } from '../domain/opportunity.state.js';
 import { OpportunityEvaluator } from './opportunity.evaluator.js';
 import { IntentIndexer } from '../../capabilities/signals.indexing.facade.js';
 import { getModelName } from '../../shared/agent/model.config.js';
@@ -2028,34 +2027,19 @@ export class OpportunityGraphFactory {
                         ? (await Promise.all(uniqueIndexIds.map((networkId) => this.agentDispatcher.hasExternalAgent(discoveryUserId, { action: 'manage:negotiations', scopeType: 'network', scopeId: networkId }).catch(() => false)))).every(Boolean)
                         : false)
                     : false;
-                // Orchestrator (chat-driven a2h) fan-out uses a tight 60s park window —
-                // the user is watching the stream, so we cannot afford the 5-min ambient
-                // budget. Ambient keeps its heartbeat-aware long/short split.
-                const ORCHESTRATOR_PARK_WINDOW_MS = 60000;
-                const isOrchestrator = state.trigger === 'orchestrator';
                 const useLongTimeout = !isChatPath || hasExternalAgent;
-                const timeoutMs = isOrchestrator
-                    ? ORCHESTRATOR_PARK_WINDOW_MS
-                    : useLongTimeout ? AMBIENT_PARK_WINDOW_MS : 30000;
+                const timeoutMs = useLongTimeout ? AMBIENT_PARK_WINDOW_MS : 30000;
                 logger.info('negotiateNode timeout decision', {
                     discoveryUserId,
-                    trigger: state.trigger,
                     isChatPath,
-                    isOrchestrator,
                     hasDispatcher: !!this.agentDispatcher,
                     hasExternalAgent,
                     useLongTimeout,
                     timeoutMs,
                     candidateCount: candidates.length,
                 });
-                // Per-candidate hook — always-on. Accumulates negotiation resolutions
-                // for discovery question generation. Additionally, for the orchestrator
-                // trigger: flips the opp from 'pending' to 'draft' and pushes an
-                // `opportunity_draft_ready` event so the frontend can render it
-                // inline as soon as it resolves, rather than waiting for the full
-                // fan-out. Abort (e.g. user closed the chat) suppresses both the
-                // status flip and the event — the in-flight negotiation finishes
-                // naturally but its card never reaches the user.
+                // Per-candidate hook accumulates negotiation resolutions for discovery
+                // question generation, preserving candidate-list order below.
                 // Build a stable order index so that resolutions accumulated via the
                 // per-candidate async hook can be re-sorted to candidate-list order
                 // before being handed to buildQuestionPrompt. Without this the LLM
@@ -2064,7 +2048,7 @@ export class OpportunityGraphFactory {
                 candidates.forEach((c, i) => candidateOrderById.set(c.userId, i));
                 const resolutions = [];
                 const resolvedOpportunityIds = new Set();
-                const onCandidateResolved = async ({ candidate, accepted, turns, outcome }) => {
+                const onCandidateResolved = async ({ candidate, turns, outcome }) => {
                     if (candidate.opportunityId)
                         resolvedOpportunityIds.add(candidate.opportunityId);
                     resolutions.push({
@@ -2085,62 +2069,11 @@ export class OpportunityGraphFactory {
                     if (candidate.opportunityId) {
                         await compensateTasklessNegotiatingOpportunity(candidate.opportunityId);
                     }
-                    if (state.trigger !== 'orchestrator')
-                        return;
-                    // ─── orchestrator streaming body ───
-                    const abortSignal = requestContext.getStore()?.abortSignal;
-                    if (abortSignal?.aborted)
-                        return;
-                    if (!accepted || !candidate.opportunityId)
-                        return;
-                    // Only emit after a successful status flip — the frontend keys
-                    // cards off `opportunity.status === 'draft'`, so emitting a row
-                    // with its pre-flip status would render inconsistently. If the
-                    // flip fails we log and drop the event; the negotiation result
-                    // is still captured in acceptedResults for the final summary.
-                    const updated = await this.database
-                        .updateOpportunityStatus(candidate.opportunityId, 'draft')
-                        .catch((err) => {
-                        negotiateLog.warn('failed to flip opp to draft; suppressing draft-ready event', {
-                            opportunityId: candidate.opportunityId,
-                            error: err,
-                        });
-                        return null;
-                    });
-                    if (!updated || abortSignal?.aborted)
-                        return;
-                    const counterpartName = candidate.candidateUser.profile?.name ?? '';
-                    const viewerName = sourceUser.profile.name;
-                    const rawReasoning = updated.interpretation?.reasoning ?? '';
-                    const personalizedSummary = safeFallbackSummary(rawReasoning, {
-                        counterpartName,
-                        viewerName,
-                        emptyText: 'A suggested connection.',
-                    });
-                    traceEmitter?.({
-                        type: 'opportunity_draft_ready',
-                        opportunityId: candidate.opportunityId,
-                        opportunity: {
-                            ...updated,
-                            interpretation: {
-                                ...updated.interpretation,
-                                reasoning: personalizedSummary,
-                            },
-                        },
-                        personalizedSummary,
-                        counterparty: {
-                            userId: candidate.candidateUser.id,
-                            ...(candidate.candidateUser.profile?.name
-                                ? { name: candidate.candidateUser.profile.name }
-                                : {}),
-                        },
-                    });
                 };
                 const negotiationWork = negotiateCandidates(this.negotiationGraph, sourceUser, candidates, { networkId: '', prompt: '' }, // base context, overridden per-candidate below
                 { maxTurns, traceEmitter: traceEmitter ?? undefined,
                     indexContextOverrides: indexContextMap,
                     timeoutMs,
-                    trigger: state.trigger === 'orchestrator' ? 'orchestrator' : 'ambient',
                     // v2 initiator stamp: every fresh-discovery origin resolves to the
                     // discovery user — querying user (chat/tool), intent owner
                     // (from-intent), enriched user (from-enrichment/discovery-run), or
@@ -2525,10 +2458,9 @@ export class OpportunityGraphFactory {
         const persistNode = withNodeTrace("opportunity-persist", async (state) => {
             return timed("OpportunityGraph.persist", async () => {
                 const startTime = Date.now();
-                const initialStatus = resolveInitialStatus(state.trigger, state.options.initialStatus);
+                const initialStatus = state.options.initialStatus ?? 'pending';
                 persistLog.verbose('Starting persistence (dedup-v2)', {
                     opportunitiesToCreate: state.evaluatedOpportunities.length,
-                    trigger: state.trigger,
                     initialStatus,
                 });
                 if (state.evaluatedOpportunities.length === 0) {
@@ -2593,41 +2525,6 @@ export class OpportunityGraphFactory {
                     const introducerUserForOnBehalf = state.onBehalfOfUserId
                         ? await this.database.getUser(state.userId)
                         : null;
-                    // Orchestrator-only: collect already-accepted pairs so Task 7's
-                    // discover_opportunities tool can tell the LLM "these pairs are
-                    // already connected, surface the existing chat rather than
-                    // creating a new draft". Runs in parallel across unique
-                    // counterparties (a single evaluator pass can return multiple
-                    // opps per counterparty; we only hit the DB once per pair).
-                    // Failures are swallowed — the per-pair query is best-effort.
-                    const dedupAlreadyAccepted = [];
-                    if (state.trigger === 'orchestrator') {
-                        // Use the same viewer-resolution as evaluation/negotiate/persist
-                        // on-behalf branches so an introducer-driven orchestrator run
-                        // queries accepted opps between the *target* user and the
-                        // counterparty, not between the introducer and the counterparty.
-                        const dedupUserId = (state.onBehalfOfUserId ?? state.userId);
-                        const uniqueCounterparts = new Set();
-                        for (const evaluated of evaluatedToPersist) {
-                            const candidateUserId = evaluated.actors.find(a => a.userId !== dedupUserId)?.userId;
-                            if (candidateUserId)
-                                uniqueCounterparts.add(candidateUserId);
-                        }
-                        const lookups = await Promise.all([...uniqueCounterparts].map(async (counterpartyUserId) => {
-                            const accepted = await this.database
-                                .findOpportunitiesByActors([dedupUserId, counterpartyUserId], { includeIntroducers: true, statuses: ['accepted'] })
-                                .catch((err) => {
-                                persistLog.warn('findOpportunitiesByActors (sibling-accept) failed', {
-                                    userId: dedupUserId,
-                                    counterpartyUserId,
-                                    error: err,
-                                });
-                                return [];
-                            });
-                            return accepted.map((opp) => ({ opportunityId: opp.id, counterpartyUserId }));
-                        }));
-                        dedupAlreadyAccepted.push(...lookups.flat());
-                    }
                     for (const evaluated of evaluatedToPersist) {
                         const indexIdForActors = state.networkId ?? evaluated.actors[0]?.networkId;
                         let actors;
@@ -3233,16 +3130,14 @@ export class OpportunityGraphFactory {
                     return {
                         opportunities: allOpportunities,
                         existingBetweenActors,
-                        dedupAlreadyAccepted,
                         persistenceOutcome,
                         trace: [{
                                 node: "persist",
-                                detail: `Created ${createdList.length}, reactivated ${reactivatedOpportunities.length}, ${existingBetweenActors.length} existing skipped, ${dedupAlreadyAccepted.length} already-accepted pair(s)`,
+                                detail: `Created ${createdList.length}, reactivated ${reactivatedOpportunities.length}, ${existingBetweenActors.length} existing skipped`,
                                 data: {
                                     created: createdList.length,
                                     reactivated: reactivatedOpportunities.length,
                                     existingSkipped: existingBetweenActors.length,
-                                    alreadyAccepted: dedupAlreadyAccepted.length,
                                     totalOutput: allOpportunities.length,
                                     persistenceOutcome,
                                     durationMs: Date.now() - startTime,
@@ -3308,7 +3203,7 @@ export class OpportunityGraphFactory {
                         return {
                             readResult: {
                                 count: 0,
-                                message: 'You have no opportunities yet. Use discover_opportunities to search for connections.',
+                                message: 'You have no opportunities yet. Create or refine an approved signal; matching runs in the background. Use list_opportunities later to review persisted results.',
                                 opportunities: [],
                             },
                         };
@@ -3494,7 +3389,6 @@ export class OpportunityGraphFactory {
                         maxTurns: Number(process.env.NEGOTIATION_MAX_TURNS_AMBIENT) || 6,
                         indexContextOverrides,
                         timeoutMs: AMBIENT_PARK_WINDOW_MS,
-                        trigger: 'ambient',
                         ...(execution ? {
                             resumeFromTaskId: execution.taskId,
                             continuationSettlementId: execution.settlementId,

package/dist/opportunity/application/opportunity.introducer-feature.d.ts

@@ -0,0 +1,2 @@
+/** Strict, default-off gate for finding opportunities on behalf of another user. */
+export declare function isIntroducerDiscoveryEnabled(): boolean;

package/dist/opportunity/application/opportunity.introducer-feature.js

@@ -0,0 +1,4 @@
+/** Strict, default-off gate for finding opportunities on behalf of another user. */
+export function isIntroducerDiscoveryEnabled() {
+    return process.env.INTRODUCER_DISCOVERY_ENABLED === "true";
+}

package/dist/opportunity/application/opportunity.owner-approval.d.ts

@@ -0,0 +1,118 @@
+/**
+ * IND-593: protocol-owned owner-approval authority port.
+ *
+ * Every registered MCP-agent opportunity state change (send/accept/reject)
+ * requires an explicit owner-issued, fresh, atomically single-use proof bound
+ * to the exact opportunity, target action, owner principal, acting agent, and
+ * current server-derived interaction. The protocol owns this verifier/consumer
+ * contract and the fail-closed boundary in `update_opportunity`; the host
+ * injects the concrete authority (challenge store + signed-proof issuance).
+ *
+ * Direct authenticated-owner interactions (REST/chat/CLI) traverse the same
+ * boundary through `attestOwnerInteraction`: the host attests the
+ * server-derived principal and interaction provenance of the already
+ * authenticated owner session. Caller-controlled identity or proof-binding
+ * fields are never trusted by either path — the binding below is always
+ * derived from the resolved tool context.
+ *
+ * A2A negotiation approvals, agent self-acknowledgment
+ * (`acknowledgedUptakeQuestionIds`), and server-generated advisory/challenge
+ * values are explicitly NOT substitutes for owner authorization.
+ */
+/** Owner-gated opportunity actions. `expired` is a system transition and is not gated. */
+export type OpportunityOwnerAction = 'send' | 'accept' | 'reject';
+/** Maps an update_opportunity target status to its owner-gated action, or null when ungated. */
+export declare function opportunityOwnerActionForStatus(status: string): OpportunityOwnerAction | null;
+/**
+ * Server-derived proof binding. Built exclusively from the resolved tool
+ * context and validated tool input — never from caller-supplied binding
+ * fields. `agentId` is present exactly when a registered agent acts.
+ */
+export interface OpportunityOwnerApprovalBinding {
+    opportunityId: string;
+    action: OpportunityOwnerAction;
+    ownerId: string;
+    agentId?: string;
+}
+/** Server-derived transport surface of the current interaction. */
+export type OpportunityOwnerInteractionSurface = 'mcp' | 'chat' | 'rest';
+/**
+ * Trusted interaction/surface provenance for a non-agent tool call (IND-593
+ * Batch B). Derived exclusively from the resolved server context — the host
+ * composition binds `isSessionAuth` from the authenticated request identity,
+ * and the surface follows the composition root (MCP server, chat factory,
+ * REST tool service). Tool arguments and caller-supplied fields can never
+ * populate it. The host authority attests ONLY a genuine direct owner
+ * session (`sessionAuthenticated` on a non-chat surface); chat/CLI/H2A/A2A
+ * and other mediated surfaces fail closed with `untrusted_provenance`.
+ */
+export interface OpportunityOwnerInteractionProvenance {
+    surface: OpportunityOwnerInteractionSurface;
+    /** True only when the host bound an authenticated owner session (never an API key or a mediated orchestrator) to this exact request. */
+    sessionAuthenticated: boolean;
+}
+/** Attestation input: the server-derived binding plus trusted provenance. */
+export type OpportunityOwnerApprovalAttestation = OpportunityOwnerApprovalBinding & {
+    provenance: OpportunityOwnerInteractionProvenance;
+};
+/** Stable, testable denial reasons for the fail-closed owner-approval boundary. */
+export type OpportunityOwnerApprovalDenialReason = 
+/** No proof presented (or no authority wired); a fresh interaction challenge is attached. */
+'missing'
+/** Proof fails authenticity/structure checks (bad signature, unknown interaction, foreign token). */
+ | 'forged'
+/** Proof or underlying challenge has expired. */
+ | 'stale'
+/** Proof is not bound to an exact opportunity/action/owner/agent/interaction. */
+ | 'generic'
+/** Proof binding mismatches the current server-derived binding. */
+ | 'wrong_owner' | 'wrong_agent' | 'wrong_action' | 'wrong_opportunity'
+/** Proof was already consumed; single-use is atomic. */
+ | 'replayed'
+/** The interaction's server-derived provenance cannot mint or attest owner authority; an owner-issued proof is required. */
+ | 'untrusted_provenance'
+/** The authority's store or configuration failed; nothing is admitted. */
+ | 'unavailable';
+/**
+ * Fresh, server-derived interaction challenge returned with a `missing`
+ * denial. The owner explicitly approves this exact interaction (bound to the
+ * full server-derived binding) to obtain a one-time proof.
+ */
+export interface OpportunityOwnerApprovalChallenge {
+    interactionId: string;
+    expiresAt: string;
+}
+export type OpportunityOwnerApprovalVerdict = {
+    kind: 'admitted';
+} | {
+    kind: 'denied';
+    reason: OpportunityOwnerApprovalDenialReason;
+    challenge?: OpportunityOwnerApprovalChallenge;
+};
+/**
+ * Authoritative owner-proof verifier/consumer, injected by the host.
+ * Implementations MUST fail closed and MUST make consumption atomically
+ * single-use: a denied verification never consumes a proof; a successful one
+ * consumes it exactly once, even under concurrent calls.
+ */
+export interface OpportunityOwnerApprovalAuthority {
+    /**
+     * Verify and atomically consume an agent-presented proof against the
+     * server-derived binding. When `proof` is undefined the implementation
+     * registers the current interaction as a fresh challenge and denies with
+     * reason `missing`, attaching the challenge so the agent can relay it to the
+     * owner for explicit approval.
+     */
+    consumeAgentProof(proof: string | undefined, binding: OpportunityOwnerApprovalBinding & {
+        agentId: string;
+    }): Promise<OpportunityOwnerApprovalVerdict>;
+    /**
+     * Traverse the same boundary for a non-agent interaction. The host attests
+     * ONLY a genuine direct authenticated-owner session, judged from the
+     * server-derived principal and interaction/surface provenance — this is
+     * authoritative host derivation, not a bypass. Mediated surfaces
+     * (chat/CLI/H2A/A2A) and absent or malformed provenance fail closed with
+     * `untrusted_provenance`.
+     */
+    attestOwnerInteraction(binding: OpportunityOwnerApprovalAttestation): Promise<OpportunityOwnerApprovalVerdict>;
+}

package/dist/opportunity/application/opportunity.owner-approval.js

@@ -0,0 +1,34 @@
+/**
+ * IND-593: protocol-owned owner-approval authority port.
+ *
+ * Every registered MCP-agent opportunity state change (send/accept/reject)
+ * requires an explicit owner-issued, fresh, atomically single-use proof bound
+ * to the exact opportunity, target action, owner principal, acting agent, and
+ * current server-derived interaction. The protocol owns this verifier/consumer
+ * contract and the fail-closed boundary in `update_opportunity`; the host
+ * injects the concrete authority (challenge store + signed-proof issuance).
+ *
+ * Direct authenticated-owner interactions (REST/chat/CLI) traverse the same
+ * boundary through `attestOwnerInteraction`: the host attests the
+ * server-derived principal and interaction provenance of the already
+ * authenticated owner session. Caller-controlled identity or proof-binding
+ * fields are never trusted by either path — the binding below is always
+ * derived from the resolved tool context.
+ *
+ * A2A negotiation approvals, agent self-acknowledgment
+ * (`acknowledgedUptakeQuestionIds`), and server-generated advisory/challenge
+ * values are explicitly NOT substitutes for owner authorization.
+ */
+/** Maps an update_opportunity target status to its owner-gated action, or null when ungated. */
+export function opportunityOwnerActionForStatus(status) {
+    switch (status) {
+        case 'pending':
+            return 'send';
+        case 'accepted':
+            return 'accept';
+        case 'rejected':
+            return 'reject';
+        default:
+            return null;
+    }
+}

package/dist/opportunity/application/opportunity.owner-provenance.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedToolContext } from "../../shared/agent/tool.helpers.js";
+import type { OpportunityOwnerInteractionProvenance } from "./opportunity.owner-approval.js";
+/** Bind authoritative host provenance to one resolved tool context. */
+export declare function bindOwnerApprovalProvenance(context: ResolvedToolContext, provenance: OpportunityOwnerInteractionProvenance): void;
+/** Read host-bound provenance without accepting any caller-supplied surrogate. */
+export declare function ownerApprovalProvenanceFor(context: ResolvedToolContext): OpportunityOwnerInteractionProvenance | undefined;

package/dist/opportunity/application/opportunity.owner-provenance.js

@@ -0,0 +1,28 @@
+/**
+ * Capability-local extension of the resolved tool context for IND-593.
+ *
+ * The host is the only writer: it binds provenance after authentication and
+ * before the registry invokes a tool. Tool input schemas never contain this
+ * field, so a caller cannot forge a direct-owner interaction through args or
+ * generic context data. Keeping this extension here avoids changing the shared
+ * helper that is part of the negotiation/question architecture cycle.
+ */
+const OWNER_APPROVAL_PROVENANCE = Symbol("ownerApprovalProvenance");
+function hasOwnerApprovalProvenance(context) {
+    return OWNER_APPROVAL_PROVENANCE in context;
+}
+/** Bind authoritative host provenance to one resolved tool context. */
+export function bindOwnerApprovalProvenance(context, provenance) {
+    Object.defineProperty(context, OWNER_APPROVAL_PROVENANCE, {
+        value: Object.freeze({ ...provenance }),
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+}
+/** Read host-bound provenance without accepting any caller-supplied surrogate. */
+export function ownerApprovalProvenanceFor(context) {
+    return hasOwnerApprovalProvenance(context)
+        ? context[OWNER_APPROVAL_PROVENANCE]
+        : undefined;
+}

package/dist/opportunity/application/opportunity.tools.d.ts

@@ -13,14 +13,14 @@ import type { ConnectLinkKind } from "../../shared/interfaces/connect-link.inter
  *   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`
+ *   `draft` case represents a pending introduction; 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)
+ *   party. Issued for a direct opportunity without an 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 —
@@ -128,4 +128,4 @@ export declare function buildMinimalOpportunityCard(opp: Opportunity, viewerId:
  * failures and drop permanent ones instead of re-spamming the ledger.
  */
 export type ConfirmDeliveryErrorCode = "unauthenticated" | "ledger_unavailable" | "invalid_opportunity_id" | "opportunity_not_found" | "not_authorized" | "confirm_failed";
-export declare function createOpportunityTools(defineTool: DefineTool, deps: OpportunityToolDeps): readonly [any, any, any, any, any, any];
+export declare function createOpportunityTools(defineTool: DefineTool, deps: OpportunityToolDeps): readonly [any, any, any];