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

package/dist/negotiations/application/negotiation.graph.screen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Negotiation graph, stage 2: the outreach gate.
+ */
+import { type ScreenDecisionRecord } from "./negotiation.screen.js";
+import type { NegotiationGraphDeps, NegotiationState } from "./negotiation.graph.shared.js";
+/**
+ * Screen node (P2.1) — the outreach gate. Runs between init and the first
+ * turn on FRESH negotiations only (routing skips it on continuations and
+ * when NEGOTIATION_SCREEN_MODE=off). The reaching client's negotiator
+ * decides whether the match is worth its client's name; in shadow mode the
+ * decision is recorded (task metadata + trace event + log line) but never
+ * blocks — the negotiation always proceeds to the first turn. In enforce
+ * mode (P2.2) a `pass` routes straight to finalize: zero turns, zero
+ * counterparty involvement, outcome `reason: "screened_out"`, opportunity
+ * quietly `rejected` (init had already flipped it to `negotiating`).
+ * A failed screen still fails OPEN in every mode.
+ */
+export declare function screenNode(state: NegotiationState, deps: NegotiationGraphDeps): Promise<{
+    screenDecision: ScreenDecisionRecord;
+    memoryBySide: {
+        [x: string]: import("../index.js").NegotiatorMemoryEntry[];
+    };
+}>;

package/dist/negotiations/application/negotiation.graph.screen.js

@@ -0,0 +1,108 @@
+/**
+ * Negotiation graph, stage 2: the outreach gate.
+ */
+import { requestContext } from "../../shared/observability/request-context.js";
+import { configuredScreenMode } from "../domain/negotiation.screen.contracts.js";
+import { buildAttributedDialogue, memoryQueryText, retrieveMemory, screenNodeLog, turnsFromMessages } from "./negotiation.graph.shared.js";
+/**
+ * Screen node (P2.1) — the outreach gate. Runs between init and the first
+ * turn on FRESH negotiations only (routing skips it on continuations and
+ * when NEGOTIATION_SCREEN_MODE=off). The reaching client's negotiator
+ * decides whether the match is worth its client's name; in shadow mode the
+ * decision is recorded (task metadata + trace event + log line) but never
+ * blocks — the negotiation always proceeds to the first turn. In enforce
+ * mode (P2.2) a `pass` routes straight to finalize: zero turns, zero
+ * counterparty involvement, outcome `reason: "screened_out"`, opportunity
+ * quietly `rejected` (init had already flipped it to `negotiating`).
+ * A failed screen still fails OPEN in every mode.
+ */
+export async function screenNode(state, deps) {
+    const traceEmitter = requestContext.getStore()?.traceEmitter;
+    const emitWide = (event) => traceEmitter?.(event);
+    const mode = configuredScreenMode();
+    const start = Date.now();
+    // The client is the initiator seat's user — the side whose negotiator is
+    // reaching out. Fresh runs stamp initiatorUserId in init; fall back to
+    // sourceUser (what the stamp defaults to anyway).
+    const initiatorId = state.initiatorUserId ?? state.sourceUser.id;
+    const clientIsSource = initiatorId !== state.candidateUser.id;
+    const clientUser = clientIsSource ? state.sourceUser : state.candidateUser;
+    const counterpartyUser = clientIsSource ? state.candidateUser : state.sourceUser;
+    // P5.3: the client's own negotiator memory informs the outreach gate.
+    // Cached into state so the client's first turn reuses it.
+    const clientSide = clientIsSource ? "source" : "candidate";
+    const clientMemory = state.memoryBySide?.[clientSide]
+        ?? (deps.memoryRetrieve
+            ? await retrieveMemory(deps, clientUser.id, counterpartyUser.id, memoryQueryText(state, counterpartyUser), "screen")
+            : []);
+    let decision;
+    let failedOpen = false;
+    let screenError;
+    try {
+        const counterpartyContext = (await deps.database.getUserContext(counterpartyUser.id, null).catch(() => null))?.text ?? "";
+        const priorDialogueAttributed = buildAttributedDialogue(state);
+        decision = await deps.screener.invoke({
+            clientUser,
+            counterpartyUser,
+            ...(counterpartyContext && { counterpartyContext }),
+            ...(clientMemory.length > 0 && { memory: clientMemory }),
+            // discoveryQuery belongs to the discovery session's source user; only
+            // meaningful for the client when the client holds the source side.
+            ...(clientIsSource && state.discoveryQuery && { discoveryQuery: state.discoveryQuery }),
+            seedAssessment: state.seedAssessment,
+            indexContext: state.indexContext,
+            isContinuation: state.isContinuation,
+            ...(state.messages.length > 0 && { priorDialogue: turnsFromMessages(state.messages) }),
+            ...(priorDialogueAttributed && { priorDialogueAttributed }),
+        });
+    }
+    catch (err) {
+        // Fail open: a screen failure must never block a negotiation.
+        failedOpen = true;
+        screenError = err instanceof Error ? err.message : String(err);
+        screenNodeLog.warn("Screen failed; proceeding open (reach_out)", {
+            taskId: state.taskId,
+            opportunityId: state.opportunityId || undefined,
+            error: screenError,
+        });
+        decision = {
+            decision: "reach_out",
+            reasoning: `screen_error: ${screenError}`,
+            evidence: { counterpartyPremiseFit: "", intentAlignment: "" },
+        };
+    }
+    const durationMs = Date.now() - start;
+    const record = {
+        ...decision,
+        mode,
+        ...(failedOpen && { failedOpen, error: screenError }),
+        screenedAt: new Date().toISOString(),
+        durationMs,
+    };
+    await deps.database.setTaskScreenDecision?.(state.taskId, record, state.continuationExecution).catch((err) => {
+        screenNodeLog.error("Failed to persist screen decision", { taskId: state.taskId, error: err });
+    });
+    screenNodeLog.info("negotiation_screen", {
+        taskId: state.taskId,
+        opportunityId: state.opportunityId || undefined,
+        decision: decision.decision,
+        mode,
+        failedOpen,
+        durationMs,
+    });
+    if (state.opportunityId) {
+        emitWide({
+            type: "negotiation_screen",
+            opportunityId: state.opportunityId,
+            negotiationConversationId: state.conversationId,
+            decision: decision.decision,
+            reasoning: decision.reasoning,
+            mode,
+            failedOpen,
+            durationMs,
+        });
+    }
+    // Routing happens on the conditional edge: shadow always proceeds to
+    // the first turn; enforce routes a (non-failed-open) pass to finalize.
+    return { screenDecision: record, memoryBySide: { [clientSide]: clientMemory } };
+}

package/dist/negotiations/application/negotiation.graph.shared.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared vocabulary for the negotiation graph's nodes.
+ *
+ * The nodes were closures inside `NegotiationGraphFactory.createGraph()`,
+ * capturing the injected database, dispatcher and queues. They are top-level
+ * functions now, each taking an explicit {@link NegotiationGraphDeps}; this
+ * module owns the bag itself and the helpers more than one node needs.
+ */
+import type { NegotiationGraphDatabase } from "../../shared/interfaces/database.interface.js";
+import type { NegotiationTimeoutQueue } from "../../shared/interfaces/negotiation-events.interface.js";
+import type { AgentDispatcher } from "../../shared/interfaces/agent-dispatcher.interface.js";
+import { NegotiationGraphState, type NegotiationTurn, type UserNegotiationContext } from "../domain/negotiation.state.js";
+import { IndexNegotiator } from "./negotiation.agent.js";
+import { NegotiationScreener } from "./negotiation.screen.js";
+import type { QuestionerEnqueueFn } from "../../questions/index.js";
+import type { ReflectEnqueueFn } from "./negotiation.reflect.js";
+import type { NegotiatorMemoryEntry, NegotiatorMemoryRetrieveFn, NegotiatorMemoryScope } from "../domain/negotiation.memory.js";
+import { type AttributedPriorDialogue, type TaskAttribution } from '../negotiation.attribution.js';
+/** The graph's channel state, as every node sees it. */
+export type NegotiationState = typeof NegotiationGraphState.State;
+/** Everything the negotiation nodes reach for. Composed once by the factory. */
+export interface NegotiationGraphDeps {
+    database: NegotiationGraphDatabase;
+    dispatcher: AgentDispatcher;
+    timeoutQueue?: NegotiationTimeoutQueue;
+    questionerEnqueue?: QuestionerEnqueueFn;
+    reflectEnqueue?: ReflectEnqueueFn;
+    memoryRetrieve?: NegotiatorMemoryRetrieveFn;
+    /** In-process negotiator used when no personal agent answers. */
+    systemAgent: IndexNegotiator;
+    /** Outreach gate for fresh negotiations. */
+    screener: NegotiationScreener;
+}
+export declare const logger: import("../../shared/observability/log.js").LoggerWithSource;
+export declare const initLog: import("../../shared/observability/log.js").LoggerWithSource;
+export declare const screenNodeLog: import("../../shared/observability/log.js").LoggerWithSource;
+export declare const turnLog: import("../../shared/observability/log.js").LoggerWithSource;
+export declare const finalizeLog: import("../../shared/observability/log.js").LoggerWithSource;
+export declare const negotiateCandidatesLog: import("../../shared/observability/log.js").LoggerWithSource;
+/** Extracts the ordered NegotiationTurn list from A2A message data parts. */
+export declare function turnsFromMessages(messages: Array<{
+    parts: unknown[];
+}>): NegotiationTurn[];
+/**
+ * Whether `userId`'s side has already spent its one `ask_user` client
+ * consultation in this conversation (P3.2 rationing: max one per negotiation
+ * per side, checked against the full message history so continuations count
+ * prior sessions' consultations too).
+ */
+export declare function hasPriorAskUser(messages: Array<{
+    senderId: string;
+    parts: unknown[];
+}>, userId: string): boolean;
+/**
+ * P5.3 memory retrieval — never throws, never blocks a negotiation. The
+ * injected fn already resolves [] when NEGOTIATOR_MEMORY_INJECT is off;
+ * this wrapper adds the graph-side failure guard.
+ */
+export declare function retrieveMemory(deps: NegotiationGraphDeps, userId: string, counterpartyUserId: string, queryText: string, scope: NegotiatorMemoryScope): Promise<NegotiatorMemoryEntry[]>;
+/** Similarity query text: seed reasoning + counterparty context. */
+export declare function memoryQueryText(state: NegotiationState, counterparty: UserNegotiationContext): string;
+/**
+ * IND-569: resolve a prior negotiation task's attribution metadata for the
+ * per-opportunity prior-dialogue labels. Never throws — any failure returns
+ * null so the turns degrade to the unattributed block instead of leaking
+ * into the current opportunity's context.
+ */
+export declare function resolveTaskAttribution(deps: NegotiationGraphDeps, taskId: string): Promise<TaskAttribution | null>;
+/**
+ * IND-569: build the attributed prior dialogue passed to the screener and
+ * turn prompts. Combines the immutable seeded attribution (earlier + legacy
+ * unattributed blocks, resolved once in init) with this session's own turns
+ * (task-id-matched). Null when there is no seeded attribution.
+ */
+export declare function buildAttributedDialogue(state: NegotiationState): AttributedPriorDialogue | null;

package/dist/negotiations/application/negotiation.graph.shared.js

@@ -0,0 +1,125 @@
+/**
+ * Shared vocabulary for the negotiation graph's nodes.
+ *
+ * The nodes were closures inside `NegotiationGraphFactory.createGraph()`,
+ * capturing the injected database, dispatcher and queues. They are top-level
+ * functions now, each taking an explicit {@link NegotiationGraphDeps}; this
+ * module owns the bag itself and the helpers more than one node needs.
+ */
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+import { attributedDialogueIsEmpty, combineAttributedDialogue } from '../negotiation.attribution.js';
+export const logger = protocolLogger("NegotiationGraph");
+export const initLog = protocolLogger("NegotiationGraph:Init");
+export const screenNodeLog = protocolLogger("NegotiationGraph:Screen");
+export const turnLog = protocolLogger("NegotiationGraph:Turn");
+export const finalizeLog = protocolLogger("NegotiationGraph:Finalize");
+export const negotiateCandidatesLog = protocolLogger("NegotiationGraph:negotiateCandidates");
+/** Extracts the ordered NegotiationTurn list from A2A message data parts. */
+export function turnsFromMessages(messages) {
+    return messages
+        .map((m) => {
+        const dataPart = m.parts.find((p) => p.kind === "data");
+        return dataPart?.data;
+    })
+        .filter(Boolean);
+}
+/**
+ * Whether `userId`'s side has already spent its one `ask_user` client
+ * consultation in this conversation (P3.2 rationing: max one per negotiation
+ * per side, checked against the full message history so continuations count
+ * prior sessions' consultations too).
+ */
+export function hasPriorAskUser(messages, userId) {
+    const sender = `agent:${userId}`;
+    return messages.some((m) => {
+        if (m.senderId !== sender)
+            return false;
+        const dataPart = m.parts.find((p) => p.kind === "data");
+        return dataPart?.data?.action === "ask_user";
+    });
+}
+/**
+ * P5.3 memory retrieval — never throws, never blocks a negotiation. The
+ * injected fn already resolves [] when NEGOTIATOR_MEMORY_INJECT is off;
+ * this wrapper adds the graph-side failure guard.
+ */
+export async function retrieveMemory(deps, userId, counterpartyUserId, queryText, scope) {
+    if (!deps.memoryRetrieve)
+        return [];
+    try {
+        return await deps.memoryRetrieve({ userId, counterpartyUserId, queryText, scope });
+    }
+    catch (err) {
+        logger.warn("Negotiator memory retrieval failed; proceeding without memory", {
+            userId,
+            scope,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return [];
+    }
+}
+/** Similarity query text: seed reasoning + counterparty context. */
+export function memoryQueryText(state, counterparty) {
+    return [
+        state.discoveryQuery ? `Search: ${state.discoveryQuery}` : "",
+        state.seedAssessment?.reasoning ?? "",
+        counterparty?.profile?.name ?? "",
+        counterparty?.profile?.bio ?? "",
+        (counterparty?.intents ?? []).slice(0, 5).map((i) => `${i.title}: ${i.description}`).join("\n"),
+    ].filter(Boolean).join("\n");
+}
+/**
+ * IND-569: resolve a prior negotiation task's attribution metadata for the
+ * per-opportunity prior-dialogue labels. Never throws — any failure returns
+ * null so the turns degrade to the unattributed block instead of leaking
+ * into the current opportunity's context.
+ */
+export async function resolveTaskAttribution(deps, taskId) {
+    try {
+        const task = await deps.database.getTask(taskId);
+        if (!task)
+            return null;
+        const md = (task.metadata ?? {});
+        const opportunityId = typeof md.opportunityId === 'string' && md.opportunityId.length > 0 ? md.opportunityId : null;
+        const snapshots = Array.isArray(md.intentSnapshots) ? md.intentSnapshots : [];
+        const sourceIntentId = typeof md.sourceIntentId === 'string' ? md.sourceIntentId : null;
+        const snap = snapshots.find((s) => s && s.intentId === sourceIntentId) ?? snapshots[0];
+        const opportunityTitle = snap && typeof snap.title === 'string' && snap.title.trim().length > 0 ? snap.title : null;
+        let outcome = null;
+        try {
+            const artifacts = await deps.database.getArtifactsForTask(taskId);
+            const outArtifact = artifacts.find((a) => a.name === 'negotiation-outcome');
+            if (outArtifact) {
+                const firstPart = Array.isArray(outArtifact.parts) ? outArtifact.parts[0] : undefined;
+                const data = firstPart?.data;
+                if (data && typeof data.hasOpportunity === 'boolean') {
+                    outcome = data.hasOpportunity ? 'accepted' : (data.reason === 'screened_out' ? 'not pursued' : 'declined');
+                }
+                else if (typeof outArtifact.metadata?.continuationOutcome === 'string') {
+                    outcome = outArtifact.metadata.continuationOutcome;
+                }
+            }
+        }
+        catch { /* outcome stays null; header degrades to "outcome unknown" */ }
+        const concludedAt = task.updatedAt instanceof Date
+            ? task.updatedAt.toISOString()
+            : (task.updatedAt ? new Date(task.updatedAt).toISOString() : null);
+        return { opportunityId, opportunityTitle, outcome, concludedAt };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * IND-569: build the attributed prior dialogue passed to the screener and
+ * turn prompts. Combines the immutable seeded attribution (earlier + legacy
+ * unattributed blocks, resolved once in init) with this session's own turns
+ * (task-id-matched). Null when there is no seeded attribution.
+ */
+export function buildAttributedDialogue(state) {
+    if (!state.isContinuation || !state.priorAttribution)
+        return null;
+    const currentSessionTurns = turnsFromMessages(state.messages.filter((m) => m.taskId === state.taskId));
+    const dialogue = combineAttributedDialogue(state.priorAttribution, currentSessionTurns);
+    return attributedDialogueIsEmpty(dialogue) ? null : dialogue;
+}

package/dist/negotiations/application/negotiation.graph.turn.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Negotiation graph, stage 3: one negotiator turn.
+ */
+import { type DeadlockShiftRecord } from "../domain/negotiation.deadlock.js";
+import type { NegotiationGraphDeps, NegotiationState } from "./negotiation.graph.shared.js";
+export declare function turnNode(state: NegotiationState, deps: NegotiationGraphDeps): Promise<{
+    status: "waiting_for_agent";
+    lastTurn?: undefined;
+    firstTurnScreenedOut?: undefined;
+    turnCount?: undefined;
+    error?: undefined;
+} | {
+    lastTurn: {
+        action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
+        assessment: {
+            reasoning: string;
+            suggestedRoles: {
+                ownUser: "agent" | "patient" | "peer";
+                otherUser: "agent" | "patient" | "peer";
+            };
+        };
+        message?: string | null | undefined;
+        askUser?: {
+            reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+        } | null | undefined;
+    };
+    firstTurnScreenedOut: boolean;
+    status?: undefined;
+    turnCount?: undefined;
+    error?: undefined;
+} | {
+    deadlockShift?: DeadlockShiftRecord | undefined;
+    messages: {
+        id: string;
+        senderId: string;
+        role: "agent";
+        parts: unknown;
+        createdAt: Date;
+    }[];
+    turnCount: number;
+    lastTurn: {
+        action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
+        assessment: {
+            reasoning: string;
+            suggestedRoles: {
+                ownUser: "agent" | "patient" | "peer";
+                otherUser: "agent" | "patient" | "peer";
+            };
+        };
+        message?: string | null | undefined;
+        askUser?: {
+            reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+        } | null | undefined;
+    };
+    status: "input_required";
+    firstTurnScreenedOut?: undefined;
+    error?: undefined;
+} | {
+    deadlockShift?: DeadlockShiftRecord | undefined;
+    outreachOpened?: boolean | undefined;
+    messages: {
+        id: string;
+        senderId: string;
+        role: "agent";
+        parts: unknown;
+        createdAt: Date;
+    }[];
+    turnCount: number;
+    currentSpeaker: "source" | "candidate";
+    lastTurn: {
+        action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
+        assessment: {
+            reasoning: string;
+            suggestedRoles: {
+                ownUser: "agent" | "patient" | "peer";
+                otherUser: "agent" | "patient" | "peer";
+            };
+        };
+        message?: string | null | undefined;
+        askUser?: {
+            reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+        } | null | undefined;
+    };
+    memoryBySide: {
+        [x: string]: import("../index.js").NegotiatorMemoryEntry[];
+    };
+    status?: undefined;
+    firstTurnScreenedOut?: undefined;
+    error?: undefined;
+} | {
+    lastTurn: {
+        action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
+        assessment: {
+            reasoning: string;
+            suggestedRoles: {
+                ownUser: "peer";
+                otherUser: "peer";
+            };
+        };
+    };
+    turnCount: number;
+    error: string;
+    status?: undefined;
+    firstTurnScreenedOut?: undefined;
+}>;