@indexnetwork/protocol 6.12.1-rc.404.1 → 6.14.0-rc.406.1

package/dist/negotiation/domain/negotiation.state.js

@@ -0,0 +1,288 @@
+import { Annotation } from "@langchain/langgraph";
+import { z } from "zod";
+import { AskUserPayloadSchema, NEGOTIATION_ACTIONS } from "../../shared/schemas/negotiation-state.schema.js";
+/**
+ * Zod schema for a single negotiation turn (DataPart payload in A2A message).
+ * Accepts the full v1+v2 action union — which subset is valid for a given turn
+ * is enforced by the seat-scoped schemas in `negotiation.protocol.ts`.
+ */
+export const NegotiationTurnSchema = z.object({
+    action: z.enum(NEGOTIATION_ACTIONS),
+    assessment: z.object({
+        reasoning: z.string(),
+        suggestedRoles: z.object({
+            ownUser: z.enum(["agent", "patient", "peer"]),
+            otherUser: z.enum(["agent", "patient", "peer"]),
+        }),
+    }),
+    message: z.string().nullable().optional(),
+    /** Present when action is `ask_user` (v2, P3.2). */
+    askUser: AskUserPayloadSchema.nullable().optional(),
+});
+/** Restricted v1 turn schema for the system agent (no question action). */
+export const SystemNegotiationTurnSchema = z.object({
+    action: z.enum(["propose", "accept", "reject", "counter"]),
+    assessment: z.object({
+        reasoning: z.string(),
+        suggestedRoles: z.object({
+            ownUser: z.enum(["agent", "patient", "peer"]),
+            otherUser: z.enum(["agent", "patient", "peer"]),
+        }),
+    }),
+    message: z.string().nullable().optional(),
+});
+/** v1 turn schema for system agent's final allowed turn (must decide). */
+export const FinalNegotiationTurnSchema = z.object({
+    action: z.enum(["accept", "reject"]),
+    assessment: z.object({
+        reasoning: z.string(),
+        suggestedRoles: z.object({
+            ownUser: z.enum(["agent", "patient", "peer"]),
+            otherUser: z.enum(["agent", "patient", "peer"]),
+        }),
+    }),
+    message: z.string().nullable().optional(),
+});
+/** Zod schema for the negotiation outcome (Artifact payload on COMPLETED task). */
+export const NegotiationOutcomeSchema = z.object({
+    hasOpportunity: z.boolean(),
+    agreedRoles: z.array(z.object({
+        userId: z.string(),
+        role: z.enum(["agent", "patient", "peer"]),
+    })),
+    reasoning: z.string(),
+    turnCount: z.number(),
+    reason: z.enum(["turn_cap", "timeout", "screened_out"]).optional(),
+});
+/** LangGraph state annotation for the negotiation graph. */
+export const NegotiationGraphState = Annotation.Root({
+    sourceUser: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => ({ id: "", intents: [], profile: {} }),
+    }),
+    candidateUser: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => ({ id: "", intents: [], profile: {} }),
+    }),
+    sourceIntentId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    candidateIntentId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    indexContext: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => ({ networkId: "", prompt: "" }),
+    }),
+    seedAssessment: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => ({ reasoning: "", valencyRole: "" }),
+    }),
+    /**
+     * Explicit initiator seat for this match (purely additive metadata — no seat
+     * rules attach to it yet). Resolution when unset happens in the init node;
+     * the resolved value is written back to state and into task metadata.
+     */
+    initiatorUserId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** The explicit search query that triggered discovery (if any). */
+    discoveryQuery: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /**
+     * Negotiation protocol version for this session's task. Resolved by the
+     * init node: inherited from the prior task on the conversation when one
+     * exists (never re-stamped — a v1 conversation stays v1 mid-flight), else
+     * stamped from `NEGOTIATION_PROTOCOL_VERSION` for genuinely fresh runs.
+     */
+    protocolVersion: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => "v1",
+    }),
+    /**
+     * Screen-gate decision for this fresh run (P2.1 shadow mode). Written by the
+     * screen node; null when the gate is off, on continuations, or before the
+     * node runs. Mirrors `tasks.metadata.screenDecision`.
+     */
+    screenDecision: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+    /**
+     * First applied deadlock→bargaining shift in this session (IND-428).
+     * Written by the turn node when the system agent first drafts in the
+     * bargaining stance; used to record the shift exactly once per session.
+     * Internal analytics only — mirrored to `tasks.metadata.deadlockShift`,
+     * never into any turn payload or public projection.
+     */
+    deadlockShift: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+    /**
+     * Per-side negotiator-memory cache (P5.3 read path). Populated lazily the
+     * first time each side's memory is retrieved (screen node for the client,
+     * turn node for the speaker) so a multi-turn session pays for retrieval at
+     * most once per side. `undefined` per side = not yet retrieved; `[]` =
+     * retrieved and empty (flag off / no rows / retrieval failed).
+     */
+    memoryBySide: Annotation({
+        reducer: (curr, next) => ({ ...curr, ...next }),
+        default: () => ({}),
+    }),
+    /** Whether this run is continuing a prior conversation with the same pair. */
+    isContinuation: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => false,
+    }),
+    /**
+     * Immutable attributed prior dialogue derived once in the init node from the
+     * seeded prior messages (IND-569). Groups earlier-opportunity turns and
+     * legacy unattributed turns so the screen node and every turn prompt can
+     * label prior context per opportunity. Null on fresh runs / when there is no
+     * seeded prior dialogue. Typed as `unknown` to avoid a module cycle
+     * (attribution module imports NegotiationTurn from this module's shim);
+     * callers cast to `SeededAttribution` via the negotiation.attribution module.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    priorAttribution: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+    /**
+     * Whether the initiator has actually opened `outreach` within THIS task
+     * (IND-564). Set by the turn node the first time an `outreach` turn is
+     * persisted in the current session; seeded prior-task turns never flip it.
+     * `withdraw` is only legal after an in-task outreach — a withdraw before one
+     * would retract an outreach never made here and drop a spurious message into
+     * the shared thread, so the turn node maps it to a quiet screen-out instead.
+     */
+    outreachOpened: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => false,
+    }),
+    /**
+     * Set by the turn node when an opening-move `withdraw` (no in-task outreach)
+     * was blocked (IND-564). Signals finalize to record the quiet screen-out
+     * outcome (`reason: "screened_out"`, opportunity `rejected`) without ever
+     * persisting the withdraw message into the shared `dm_pair` conversation.
+     */
+    firstTurnScreenedOut: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => false,
+    }),
+    opportunityId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => "",
+    }),
+    /** Exact persisted lifecycle state claimed by this negotiation attempt. */
+    opportunityStatus: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    opportunityUpdatedAt: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Exact prior task selected by a durable continuation; bypasses latest-task lookup. */
+    resumeFromTaskId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Deterministic settlement key used to idempotently reuse a successor task. */
+    continuationSettlementId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    continuationExecution: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    continuationReceipt: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    privateConsultation: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Server-only IND-508 category recovered from the exact prior task binding. */
+    consultationPolicyReason: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    conversationId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => "",
+    }),
+    taskId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => "",
+    }),
+    messages: Annotation({
+        reducer: (curr, next) => [...curr, ...(next || [])],
+        default: () => [],
+    }),
+    turnCount: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 0,
+    }),
+    maxTurns: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /**
+     * Park-window budget in milliseconds. Ambient callers pass `AMBIENT_PARK_WINDOW_MS`
+     * (5 minutes); orchestrator callers pass a shorter window. This annotation default
+     * is a safety net for any caller that omits the field — keep it aligned with
+     * `AMBIENT_PARK_WINDOW_MS` in packages/protocol/src/negotiation/negotiation.tools.ts.
+     * Inlined rather than imported to avoid a state↔tools cycle.
+     */
+    timeoutMs: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 5 * 60 * 1000,
+    }),
+    currentSpeaker: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => "source",
+    }),
+    lastTurn: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+    /**
+     * Graph status.
+     * - `active` — agents are exchanging turns (default)
+     * - `waiting_for_agent` — graph suspended; awaiting external agent response or timeout
+     * - `input_required` — graph suspended on an `ask_user` pause; awaiting the
+     *   negotiator's own client (answer or 24 h window expiry resumes it)
+     * - `completed` — negotiation finalized (accept/reject/turn-cap/timeout)
+     */
+    status: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 'active',
+    }),
+    /** Number of turns present in the conversation before this session started. */
+    priorTurnCount: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 0,
+    }),
+    /** User answers collected by the questioner between negotiation sessions. */
+    userAnswers: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    outcome: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+    error: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+});

package/dist/negotiation/domain/negotiation.task-lock-policy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a persisted negotiation task still admits an exclusive conversation
+ * lock. A paused `ask_user` consultation holds the lock for its complete
+ * answer window plus expiry-worker slack; ordinary active turns use the
+ * existing five-minute freshness window.
+ */
+export declare function holdsNegotiationConversationLock(task: {
+    state: string;
+    updatedAt: Date;
+}, now?: number): boolean;

package/dist/negotiation/domain/negotiation.task-lock-policy.js

@@ -0,0 +1,22 @@
+import { ASK_USER_LOCK_SLACK_MS, askUserAnswerWindowMs } from "./negotiation.protocol.js";
+const ACTIVE_NEGOTIATION_TASK_STATES = [
+    "submitted",
+    "working",
+    "input_required",
+    "waiting_for_agent",
+    "claimed",
+];
+/**
+ * Whether a persisted negotiation task still admits an exclusive conversation
+ * lock. A paused `ask_user` consultation holds the lock for its complete
+ * answer window plus expiry-worker slack; ordinary active turns use the
+ * existing five-minute freshness window.
+ */
+export function holdsNegotiationConversationLock(task, now = Date.now()) {
+    if (!ACTIVE_NEGOTIATION_TASK_STATES.includes(task.state))
+        return false;
+    const freshnessMs = task.state === "input_required"
+        ? askUserAnswerWindowMs() + ASK_USER_LOCK_SLACK_MS
+        : 5 * 60 * 1000;
+    return now - new Date(task.updatedAt).getTime() < freshnessMs;
+}

package/dist/negotiation/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * negotiation — domain-first module root.
+ *
+ * Re-exports the curated public surface. Other modules inside the negotiation
+ * capability import directly from negotiation/domain, negotiation/application,
+ * or negotiation/ports; this barrel is for cross-capability consumers that must
+ * go through the negotiation public surface.
+ *
+ * IND-550: canonical home for the bilateral turn protocol, screening, memory,
+ * consultation, settlement, and summary capabilities previously spread across
+ * the flat negotiation/ directory and capabilities/negotiation*.facade.ts files.
+ *
+ * ## Module topology
+ *
+ * ```
+ * negotiation/
+ * ├── domain/       — pure types, protocol rules, policy functions, renderers
+ * ├── application/  — LLM agents, LangGraph factory, MCP tool factory
+ * ├── ports/        — injected dependency contracts (NegotiationToolDeps)
+ * ├── public/       — curated re-export surface
+ * └── index.ts      — this file
+ * ```
+ *
+ * ## Legacy paths (thin inward shims)
+ *
+ * The following old flat-file paths are preserved as thin re-export shims for
+ * backward compatibility with test files and runtime composition:
+ * - negotiation/negotiation.state.ts → domain
+ * - negotiation/negotiation.protocol.ts → domain
+ * - negotiation/negotiation.deadlock.ts → domain
+ * - negotiation/negotiation.deadlock.contracts.ts → domain
+ * - negotiation/negotiation.lifecycle-narration.ts → domain
+ * - negotiation/negotiation.task-lock-policy.ts → domain
+ * - negotiation/negotiation.intent-snapshot-provenance.ts → domain
+ * - negotiation/negotiation.consultation-policy.ts → domain
+ * - negotiation/negotiation.question-safety.ts → domain
+ * - negotiation/negotiation.memory.ts → domain
+ * - negotiation/negotiation.graph.ts → application
+ * - negotiation/negotiation.agent.ts → application
+ * - negotiation/negotiation.screen.ts → application (+ screen contracts from domain)
+ * - negotiation/negotiation.reflect.ts → application
+ * - negotiation/negotiation.summarizer.ts → application
+ * - negotiation/negotiation.tools.ts → application
+ * - negotiation/negotiation.detail-reader.ts → application
+ * - negotiation/insight.generator.ts → application
+ * - capabilities/negotiation*.facade.ts → public surface
+ * - capabilities/negotiation.tools.port.ts → ports
+ */
+export * from "./public/index.js";

package/dist/negotiation/index.js

@@ -0,0 +1,49 @@
+/**
+ * negotiation — domain-first module root.
+ *
+ * Re-exports the curated public surface. Other modules inside the negotiation
+ * capability import directly from negotiation/domain, negotiation/application,
+ * or negotiation/ports; this barrel is for cross-capability consumers that must
+ * go through the negotiation public surface.
+ *
+ * IND-550: canonical home for the bilateral turn protocol, screening, memory,
+ * consultation, settlement, and summary capabilities previously spread across
+ * the flat negotiation/ directory and capabilities/negotiation*.facade.ts files.
+ *
+ * ## Module topology
+ *
+ * ```
+ * negotiation/
+ * ├── domain/       — pure types, protocol rules, policy functions, renderers
+ * ├── application/  — LLM agents, LangGraph factory, MCP tool factory
+ * ├── ports/        — injected dependency contracts (NegotiationToolDeps)
+ * ├── public/       — curated re-export surface
+ * └── index.ts      — this file
+ * ```
+ *
+ * ## Legacy paths (thin inward shims)
+ *
+ * The following old flat-file paths are preserved as thin re-export shims for
+ * backward compatibility with test files and runtime composition:
+ * - negotiation/negotiation.state.ts → domain
+ * - negotiation/negotiation.protocol.ts → domain
+ * - negotiation/negotiation.deadlock.ts → domain
+ * - negotiation/negotiation.deadlock.contracts.ts → domain
+ * - negotiation/negotiation.lifecycle-narration.ts → domain
+ * - negotiation/negotiation.task-lock-policy.ts → domain
+ * - negotiation/negotiation.intent-snapshot-provenance.ts → domain
+ * - negotiation/negotiation.consultation-policy.ts → domain
+ * - negotiation/negotiation.question-safety.ts → domain
+ * - negotiation/negotiation.memory.ts → domain
+ * - negotiation/negotiation.graph.ts → application
+ * - negotiation/negotiation.agent.ts → application
+ * - negotiation/negotiation.screen.ts → application (+ screen contracts from domain)
+ * - negotiation/negotiation.reflect.ts → application
+ * - negotiation/negotiation.summarizer.ts → application
+ * - negotiation/negotiation.tools.ts → application
+ * - negotiation/negotiation.detail-reader.ts → application
+ * - negotiation/insight.generator.ts → application
+ * - capabilities/negotiation*.facade.ts → public surface
+ * - capabilities/negotiation.tools.port.ts → ports
+ */
+export * from "./public/index.js";

package/dist/negotiation/insight.generator.d.ts

@@ -1,32 +1,5 @@
 /**
- * Negotiation Insights Generator
- *
- * Produces an aggregated, second-person narrative summarizing a user's
- * negotiation history — topics they're sought for, role patterns,
- * opportunity trends, and interesting signals from recent activity.
+ * Thin backward-compat shim — IND-550.
+ * Canonical location: negotiation/application/insight.generator.ts
  */
-/** Compressed digest of a user's negotiation history for the LLM. */
-export interface NegotiationDigest {
-    totalCount: number;
-    opportunityCount: number;
-    noOpportunityCount: number;
-    inProgressCount: number;
-    roleDistribution: Record<string, number>;
-    counterparties: string[];
-    reasoningExcerpts: string[];
-}
-/**
- * Generates an aggregated insight summary from a user's negotiation history.
- * @remarks Lightweight single-call agent; no DB access, no side effects.
- */
-export declare class NegotiationInsightsGenerator {
-    private model;
-    constructor();
-    /**
-     * Produces a narrative summary from a negotiation digest.
-     * @param digest - Pre-computed statistics and excerpts from the user's negotiations
-     * @returns A 2-4 sentence insight paragraph, or null on failure
-     */
-    invoke(digest: NegotiationDigest): Promise<string | null>;
-}
-//# sourceMappingURL=insight.generator.d.ts.map
+export * from "./application/insight.generator.js";

package/dist/negotiation/insight.generator.js

@@ -1,106 +1,5 @@
 /**
- * Negotiation Insights Generator
- *
- * Produces an aggregated, second-person narrative summarizing a user's
- * negotiation history — topics they're sought for, role patterns,
- * opportunity trends, and interesting signals from recent activity.
+ * Thin backward-compat shim — IND-550.
+ * Canonical location: negotiation/application/insight.generator.ts
  */
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-import { HumanMessage, SystemMessage } from "@langchain/core/messages";
-import { log } from "../shared/observability/log.js";
-import { Timed } from "../shared/observability/performance.js";
-import { createResilientModel } from "../shared/agent/model.config.js";
-import { invokeWithAbortSignal } from "../shared/agent/model-signal.js";
-const logger = log.lib.from("NegotiationInsightsGenerator");
-const SYSTEM_PROMPT = `You are an analyst summarizing a user's negotiation history on a discovery network.
-Agents negotiate on behalf of users to find collaboration opportunities.
-
-Given a digest of past negotiations, write a concise insight paragraph (2-4 sentences) addressed to the user in second person ("you").
-
-Guidelines:
-- Be conversational and insightful, not just statistical.
-- Highlight what others seek the user for, and what the user tends to seek.
-- Mention role patterns: Helper (they assist others), Seeker (they need something), Peer (mutual collaboration).
-- Note opportunity rate trends or interesting shifts if apparent.
-- Reference specific topics or counterparty names when they form patterns.
-- If there are very few negotiations (1-2), keep it brief and forward-looking.
-- Do NOT use bullet points or lists. Write flowing prose.
-- Do NOT start with "You have" or "Your negotiations". Be more creative.`;
-/**
- * Generates an aggregated insight summary from a user's negotiation history.
- * @remarks Lightweight single-call agent; no DB access, no side effects.
- */
-export class NegotiationInsightsGenerator {
-    constructor() {
-        this.model = createResilientModel("negotiationInsights");
-    }
-    /**
-     * Produces a narrative summary from a negotiation digest.
-     * @param digest - Pre-computed statistics and excerpts from the user's negotiations
-     * @returns A 2-4 sentence insight paragraph, or null on failure
-     */
-    async invoke(digest) {
-        if (digest.totalCount === 0)
-            return null;
-        const lines = [
-            `Total negotiations: ${digest.totalCount}`,
-            `Opportunities: ${digest.opportunityCount}, No opportunity: ${digest.noOpportunityCount}, In progress: ${digest.inProgressCount}`,
-        ];
-        const roles = Object.entries(digest.roleDistribution);
-        if (roles.length > 0) {
-            lines.push(`Role distribution: ${roles.map(([r, n]) => `${r}: ${n}`).join(", ")}`);
-        }
-        if (digest.counterparties.length > 0) {
-            lines.push(`Counterparties: ${digest.counterparties.join(", ")}`);
-        }
-        if (digest.reasoningExcerpts.length > 0) {
-            lines.push(`Sample reasoning excerpts:\n${digest.reasoningExcerpts.map((r) => `- ${r}`).join("\n")}`);
-        }
-        const userMessage = `Negotiation digest:\n${lines.join("\n")}\n\nWrite the insight summary:`;
-        try {
-            const response = await invokeWithAbortSignal(this.model, [
-                new SystemMessage(SYSTEM_PROMPT),
-                new HumanMessage(userMessage),
-            ]);
-            let text;
-            if (typeof response.content === "string") {
-                text = response.content.trim();
-            }
-            else if (Array.isArray(response.content)) {
-                text = response.content
-                    .filter((b) => b.type === "text")
-                    .map((b) => b.text ?? "")
-                    .join("")
-                    .trim();
-            }
-            else {
-                text = "";
-            }
-            if (!text)
-                return null;
-            logger.verbose("Insights generated", { length: text.length });
-            return text;
-        }
-        catch (error) {
-            logger.warn("Failed to generate insights", {
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return null;
-        }
-    }
-}
-__decorate([
-    Timed(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
-    __metadata("design:returntype", Promise)
-], NegotiationInsightsGenerator.prototype, "invoke", null);
-//# sourceMappingURL=insight.generator.js.map
+export * from "./application/insight.generator.js";