@indexnetwork/protocol 6.12.0-rc.403.1 → 6.13.22-rc.405.1

package/dist/negotiation/domain/negotiation.protocol.js

@@ -0,0 +1,202 @@
+/**
+ * Seat-scoped negotiation protocol rules (v2 client-advocate protocol).
+ *
+ * v2 fixes exactly one initiating seat per match (`metadata.initiatorUserId`,
+ * stamped at discovery time — IND-396) and makes consent asymmetric:
+ * **accept can only come from the counterparty seat**, schema-enforced.
+ *
+ * Vocabulary per seat (v2):
+ * - initiator:     `outreach | counter | question | withdraw`  (no accept)
+ * - counterparty:  `accept | decline | counter | question`
+ * - final turn:    initiator `withdraw | counter`; counterparty `accept | decline`
+ *
+ * v1 tasks keep the legacy vocabulary (`propose | accept | reject | counter |
+ * question`) — the version is inherited per conversation, never re-stamped, so
+ * in-flight v1 negotiations are grandfathered untouched.
+ *
+ * Outcome mapping is version-independent: `accept` → opportunity `pending`,
+ * `reject`/`withdraw`/`decline` → `rejected`, turn-cap → `stalled`.
+ */
+import { z } from "zod";
+import { AskUserPayloadSchema } from "../../shared/schemas/negotiation-state.schema.js";
+// ─── Shared assessment fragment ──────────────────────────────────────────────
+const AssessmentSchema = z.object({
+    reasoning: z.string(),
+    suggestedRoles: z.object({
+        ownUser: z.enum(["agent", "patient", "peer"]),
+        otherUser: z.enum(["agent", "patient", "peer"]),
+    }),
+});
+function turnSchema(actions) {
+    return z.object({
+        action: z.enum(actions),
+        assessment: AssessmentSchema,
+        message: z.string().nullable().optional(),
+        /** Present when action is `ask_user` (v2, P3.2). */
+        askUser: AskUserPayloadSchema.nullable().optional(),
+    });
+}
+// ─── v2 seat-scoped turn schemas ─────────────────────────────────────────────
+/** Initiator seat, non-final turn: may reach out, push back, ask, or walk away — never accept. */
+export const InitiatorTurnSchema = turnSchema(["outreach", "counter", "question", "withdraw"]);
+/** Counterparty seat, non-final turn: the only seat that can accept. */
+export const CounterpartyTurnSchema = turnSchema(["accept", "decline", "counter", "question"]);
+/** Initiator seat, final allowed turn: commit to walking away or leave the door open. */
+export const FinalInitiatorTurnSchema = turnSchema(["withdraw", "counter"]);
+/** Counterparty seat, final allowed turn: must decide. */
+export const FinalCounterpartyTurnSchema = turnSchema(["accept", "decline"]);
+// ─── v2 ask_user variants (P3.2, flag-gated) ────────────────────────────────
+// Non-final turns only: the final-cap turn must decide, never pause. Selected
+// via the `opts.askUser` parameter on allowedActionsFor/turnSchemaFor — the
+// base schemas above stay byte-identical for every existing caller.
+/** Initiator seat, non-final turn, with the client-consult pause available. */
+export const InitiatorAskUserTurnSchema = turnSchema(["outreach", "counter", "question", "withdraw", "ask_user"]);
+/** Counterparty seat, non-final turn, with the client-consult pause available. */
+export const CounterpartyAskUserTurnSchema = turnSchema(["accept", "decline", "counter", "question", "ask_user"]);
+// ─── Action vocabulary per version + seat ────────────────────────────────────
+const V1_ACTIONS = ["propose", "accept", "reject", "counter", "question"];
+const V1_FINAL_ACTIONS = ["accept", "reject"];
+const V2_INITIATOR_ACTIONS = ["outreach", "counter", "question", "withdraw"];
+const V2_COUNTERPARTY_ACTIONS = ["accept", "decline", "counter", "question"];
+const V2_FINAL_INITIATOR_ACTIONS = ["withdraw", "counter"];
+const V2_FINAL_COUNTERPARTY_ACTIONS = ["accept", "decline"];
+const V2_INITIATOR_ASK_USER_ACTIONS = [...V2_INITIATOR_ACTIONS, "ask_user"];
+const V2_COUNTERPARTY_ASK_USER_ACTIONS = [...V2_COUNTERPARTY_ACTIONS, "ask_user"];
+/**
+ * The set of actions a given seat may submit under a given protocol version.
+ *
+ * v1 ignores the seat entirely (legacy symmetric vocabulary) so pre-v2
+ * negotiations behave exactly as before.
+ */
+export function allowedActionsFor(version, seat, isFinalTurn = false, opts) {
+    if (version !== "v2")
+        return isFinalTurn ? V1_FINAL_ACTIONS : V1_ACTIONS;
+    const askUser = opts?.askUser === true && !isFinalTurn;
+    if (seat === "initiator") {
+        return isFinalTurn ? V2_FINAL_INITIATOR_ACTIONS : (askUser ? V2_INITIATOR_ASK_USER_ACTIONS : V2_INITIATOR_ACTIONS);
+    }
+    return isFinalTurn ? V2_FINAL_COUNTERPARTY_ACTIONS : (askUser ? V2_COUNTERPARTY_ASK_USER_ACTIONS : V2_COUNTERPARTY_ACTIONS);
+}
+/**
+ * Zod turn schema for a system-agent turn, selected by version + seat +
+ * final-turn flag. v1 returns the legacy schemas (seat-agnostic); v2 returns
+ * the seat-scoped schemas above, making an initiator `accept` structurally
+ * impossible rather than prompt-discouraged.
+ *
+ * The v1 legacy schemas are passed in by the caller (they live in
+ * `negotiation.state.ts`) to keep this module free of a state-module import.
+ */
+export function turnSchemaFor(version, seat, isFinalTurn, v1Schemas, opts) {
+    if (version !== "v2")
+        return isFinalTurn ? v1Schemas.final : v1Schemas.system;
+    const askUser = opts?.askUser === true && !isFinalTurn;
+    if (seat === "initiator") {
+        return isFinalTurn ? FinalInitiatorTurnSchema : (askUser ? InitiatorAskUserTurnSchema : InitiatorTurnSchema);
+    }
+    return isFinalTurn ? FinalCounterpartyTurnSchema : (askUser ? CounterpartyAskUserTurnSchema : CounterpartyTurnSchema);
+}
+// ─── Action semantics (version-independent) ──────────────────────────────────
+/** Terminal actions end the negotiation immediately. */
+export function isTerminalAction(action) {
+    return action === "accept" || action === "reject" || action === "withdraw" || action === "decline";
+}
+/** Reject-like actions map the opportunity to `rejected` (v1 reject, v2 withdraw/decline). */
+export function isRejectLikeAction(action) {
+    return action === "reject" || action === "withdraw" || action === "decline";
+}
+/**
+ * Conservative action when an agent produced schema-invalid output (after the
+ * retry) or an internal error needs a seat-valid terminal placeholder.
+ *
+ * Non-final turns fall back to `counter` (keeps the dialogue open — the AC's
+ * "conservative counter"). Final turns must decide: v1 → `reject`, v2
+ * counterparty → `decline`, v2 initiator → `counter` is still legal on the
+ * final turn so it stays `counter` (finalizes as turn-cap/stalled).
+ */
+export function fallbackActionFor(version, seat, isFinalTurn) {
+    if (!isFinalTurn)
+        return "counter";
+    if (version !== "v2")
+        return "reject";
+    return seat === "counterparty" ? "decline" : "counter";
+}
+/** Seat-appropriate reject-like action for error paths. */
+export function rejectActionFor(version, seat) {
+    if (version !== "v2")
+        return "reject";
+    return seat === "initiator" ? "withdraw" : "decline";
+}
+// ─── Metadata readers ────────────────────────────────────────────────────────
+/**
+ * Read the protocol version off task metadata. Returns null when the task
+ * predates version stamping (treat as v1 at the call site when the task is a
+ * genuine prior; fresh tasks stamp from {@link configuredProtocolVersion}).
+ */
+export function readProtocolVersion(metadata) {
+    const v = metadata?.protocolVersion;
+    return v === "v2" ? "v2" : v === "v1" ? "v1" : null;
+}
+/**
+ * Protocol version for negotiations without a prior task for the same
+ * opportunity, from the `NEGOTIATION_PROTOCOL_VERSION` env switch. Defaults
+ * to `v1` when unset — v2 is opt-in per environment, and rolling back is the
+ * same single switch (only in-flight negotiations stay pinned to their
+ * stamped version).
+ */
+export function configuredProtocolVersion() {
+    return process.env.NEGOTIATION_PROTOCOL_VERSION === "v2" ? "v2" : "v1";
+}
+/**
+ * Whether the `ask_user` client-consult pause (P3.2) is enabled, from the
+ * `NEGOTIATION_ASK_USER_ENABLED` env switch. Defaults to off — the deployment
+ * is byte-for-byte unchanged until the flag is flipped, and rolling back is
+ * the same single switch.
+ */
+export function configuredAskUserEnabled() {
+    return process.env.NEGOTIATION_ASK_USER_ENABLED === "true";
+}
+/** Default answer window for a paused `ask_user` negotiation: 24 hours. */
+export const DEFAULT_ASK_USER_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * Answer window for a paused `ask_user` negotiation, in ms. Overridable via
+ * `NEGOTIATION_ASK_USER_WINDOW_MS` (dev/e2e use shorter windows to exercise
+ * the expiry path); invalid or non-positive values fall back to 24 h.
+ */
+export function askUserAnswerWindowMs() {
+    const raw = process.env.NEGOTIATION_ASK_USER_WINDOW_MS;
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_ASK_USER_WINDOW_MS;
+}
+/**
+ * Slack added on top of the answer window when deciding whether a paused
+ * (`input_required`) task still holds the conversation lock. Covers expiry
+ * worker delay: the lock must outlive the timer slightly, so ambient
+ * rediscovery cannot slip in between window expiry and the worker's resume.
+ */
+export const ASK_USER_LOCK_SLACK_MS = 60 * 60 * 1000;
+/**
+ * Resolve the seat of `userId` on a negotiation task.
+ *
+ * Keys on `metadata.initiatorUserId` (the rigid v2 stamp), **never on turn
+ * parity** — continuations can start with either side speaking first, so
+ * parity misattributes seats across sessions. Pre-stamp tasks fall back to
+ * `sourceUserId` (the discovery-session opener), which is what the stamp
+ * defaults to anyway.
+ */
+export function resolveSeat(userId, metadata) {
+    const initiator = typeof metadata?.initiatorUserId === "string" && metadata.initiatorUserId.length > 0
+        ? metadata.initiatorUserId
+        : typeof metadata?.sourceUserId === "string"
+            ? metadata.sourceUserId
+            : undefined;
+    return initiator === userId ? "initiator" : "counterparty";
+}
+/** Human-readable seat-violation message shared by respond surfaces. */
+export function seatViolationMessage(action, seat, version) {
+    const allowed = allowedActionsFor(version, seat).join(", ");
+    return `Action "${action}" is not allowed for your seat (${seat}) under negotiation protocol ${version}. Allowed actions: ${allowed}.`;
+}

package/dist/negotiation/domain/negotiation.question-safety.d.ts

@@ -0,0 +1,25 @@
+/** Fixed prompt-safe labels; producers must not replace them with raw network/counterparty text. */
+export declare const NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY = "the other participant";
+export declare const NEGOTIATION_QUESTION_GENERIC_NETWORK = "the selected network";
+export declare const NEGOTIATION_QUESTION_GENERIC_UPTAKE_ACTIVITY = "a potential collaboration that may require clarification before you decide";
+/**
+ * Deterministically reject question context copied from private negotiation inputs.
+ * This guard never rewrites content: unsafe or ambiguous text yields no card while
+ * the already-armed timeout retains the conservative continuation path.
+ */
+export declare function isSafeNegotiationQuestionText(value: string, options?: {
+    forbiddenIdentifiers?: string[];
+    forbiddenSourceText?: string[];
+}): boolean;
+/** Validate the only structured fields allowed to enter the inflight Questioner prompt. */
+export declare function validateInflightAskUserFields(input: {
+    disclosureSubject?: string | null;
+    draftQuestion?: string | null;
+    forbiddenIdentifiers?: string[];
+    forbiddenSourceText?: string[];
+}): {
+    disclosureSubject: string;
+    draftQuestion?: string;
+} | null;
+/** Stable, non-secret settlement/outbox key derived only from the exact paused task. */
+export declare function negotiationQuestionSettlementId(taskId: string): string;

package/dist/negotiation/domain/negotiation.question-safety.js

@@ -0,0 +1,55 @@
+import { hasUnsupportedOpportunityClaim } from '../../capabilities/opportunities.safety.facade.js';
+/** Fixed prompt-safe labels; producers must not replace them with raw network/counterparty text. */
+export const NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY = 'the other participant';
+export const NEGOTIATION_QUESTION_GENERIC_NETWORK = 'the selected network';
+export const NEGOTIATION_QUESTION_GENERIC_UPTAKE_ACTIVITY = 'a potential collaboration that may require clarification before you decide';
+const INTERNAL_ID_PATTERN = /\b(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|(?:task|intent|network|opportunity|user|match)[_-]?id)\b/i;
+const PRIVATE_SOURCE_PATTERN = /\b(?:private transcript|raw transcript|assessment(?:\.reasoning)?|seed assessment|evaluator reasoning|match reason|matchReason|internal metadata|counterparty profile)\b/i;
+function normalize(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+/**
+ * Deterministically reject question context copied from private negotiation inputs.
+ * This guard never rewrites content: unsafe or ambiguous text yields no card while
+ * the already-armed timeout retains the conservative continuation path.
+ */
+export function isSafeNegotiationQuestionText(value, options) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || trimmed.length > 600)
+        return false;
+    if (INTERNAL_ID_PATTERN.test(trimmed) || PRIVATE_SOURCE_PATTERN.test(trimmed))
+        return false;
+    if (hasUnsupportedOpportunityClaim(trimmed))
+        return false;
+    const normalized = normalize(trimmed);
+    for (const identifier of options?.forbiddenIdentifiers ?? []) {
+        const forbidden = normalize(identifier);
+        if (forbidden.length >= 3 && new RegExp(`(?:^| )${forbidden.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?: |$)`).test(normalized)) {
+            return false;
+        }
+    }
+    for (const source of options?.forbiddenSourceText ?? []) {
+        const forbidden = normalize(source);
+        if (forbidden.length >= 24 && (normalized.includes(forbidden) || forbidden.includes(normalized))) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Validate the only structured fields allowed to enter the inflight Questioner prompt. */
+export function validateInflightAskUserFields(input) {
+    const disclosureSubject = input.disclosureSubject?.trim();
+    if (!disclosureSubject || !isSafeNegotiationQuestionText(disclosureSubject, input))
+        return null;
+    const draftQuestion = input.draftQuestion?.trim();
+    if (draftQuestion && !isSafeNegotiationQuestionText(draftQuestion, input))
+        return null;
+    return {
+        disclosureSubject,
+        ...(draftQuestion ? { draftQuestion } : {}),
+    };
+}
+/** Stable, non-secret settlement/outbox key derived only from the exact paused task. */
+export function negotiationQuestionSettlementId(taskId) {
+    return `negotiation-question-settlement-v1-${taskId}`;
+}

package/dist/negotiation/domain/negotiation.screen.contracts.d.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/**
+ * negotiation/domain — screen-gate pure contracts (P2.1).
+ *
+ * Extracted from negotiation.screen.ts so that NegotiationGraphState and the
+ * application-layer NegotiationScreener can share types without a domain →
+ * application cycle.
+ *
+ * IND-550: canonical location for screen contract types.
+ * Legacy path (negotiation/negotiation.screen.ts shim) re-exports from here
+ * via the application layer.
+ */
+export declare const NEGOTIATION_SCREEN_MODES: readonly ["off", "shadow", "enforce"];
+export type NegotiationScreenMode = (typeof NEGOTIATION_SCREEN_MODES)[number];
+/**
+ * Resolve the screen mode from `NEGOTIATION_SCREEN_MODE`.
+ *
+ * Defaults to `off` when unset or unrecognized — the screen gate is an
+ * explicit opt-in flip (same operational pattern as
+ * `NEGOTIATION_PROTOCOL_VERSION` / `NEGOTIATOR_CHAT_ENABLED`): code ships
+ * inert, the environment turns it on.
+ */
+export declare function configuredScreenMode(): NegotiationScreenMode;
+/**
+ * Structured screen decision — the outreach gate's verdict on whether this
+ * match is worth the client's name before any turn is exchanged.
+ */
+export declare const ScreenDecisionSchema: z.ZodObject<{
+    decision: z.ZodEnum<["reach_out", "pass"]>;
+    reasoning: z.ZodString;
+    /** Suggested opening angle for the outreach turn (only when reaching out). */
+    outreachAngle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    evidence: z.ZodObject<{
+        /** How well the counterparty's context/premises fit the client's need. */
+        counterpartyPremiseFit: z.ZodString;
+        /** How the client's intents align with what the counterparty seeks. */
+        intentAlignment: z.ZodString;
+        /** Prior-negotiation memory signals (P5.3). Filled only when negotiator memory was injected into the screen prompt. */
+        memoryHints: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        counterpartyPremiseFit: string;
+        intentAlignment: string;
+        memoryHints?: string | null | undefined;
+    }, {
+        counterpartyPremiseFit: string;
+        intentAlignment: string;
+        memoryHints?: string | null | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    reasoning: string;
+    evidence: {
+        counterpartyPremiseFit: string;
+        intentAlignment: string;
+        memoryHints?: string | null | undefined;
+    };
+    decision: "reach_out" | "pass";
+    outreachAngle?: string | null | undefined;
+}, {
+    reasoning: string;
+    evidence: {
+        counterpartyPremiseFit: string;
+        intentAlignment: string;
+        memoryHints?: string | null | undefined;
+    };
+    decision: "reach_out" | "pass";
+    outreachAngle?: string | null | undefined;
+}>;
+export type ScreenDecision = z.infer<typeof ScreenDecisionSchema>;
+/**
+ * The record persisted to `tasks.metadata.screenDecision` and returned into
+ * graph state. Extends the LLM decision with operational context so pass-rate
+ * queries can group by mode and exclude failed-open rows.
+ */
+export interface ScreenDecisionRecord extends ScreenDecision {
+    mode: NegotiationScreenMode;
+    /** True when the screen LLM call failed and the gate defaulted open. */
+    failedOpen?: boolean;
+    /** Error message when `failedOpen` is set. */
+    error?: string;
+    screenedAt: string;
+    durationMs: number;
+}
+/**
+ * Whether an enforce-mode outreach screen blocks a negotiation before any
+ * turn is exchanged. Shadow-mode pass decisions are recorded but never block.
+ * Failed-open rows are treated as reach_out regardless of `decision`.
+ */
+export declare function blocksNegotiationBeforeFirstTurn(decisionRecord: ScreenDecisionRecord | null | undefined, turnCount: number): boolean;

package/dist/negotiation/domain/negotiation.screen.contracts.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+/**
+ * negotiation/domain — screen-gate pure contracts (P2.1).
+ *
+ * Extracted from negotiation.screen.ts so that NegotiationGraphState and the
+ * application-layer NegotiationScreener can share types without a domain →
+ * application cycle.
+ *
+ * IND-550: canonical location for screen contract types.
+ * Legacy path (negotiation/negotiation.screen.ts shim) re-exports from here
+ * via the application layer.
+ */
+export const NEGOTIATION_SCREEN_MODES = ["off", "shadow", "enforce"];
+/**
+ * Resolve the screen mode from `NEGOTIATION_SCREEN_MODE`.
+ *
+ * Defaults to `off` when unset or unrecognized — the screen gate is an
+ * explicit opt-in flip (same operational pattern as
+ * `NEGOTIATION_PROTOCOL_VERSION` / `NEGOTIATOR_CHAT_ENABLED`): code ships
+ * inert, the environment turns it on.
+ */
+export function configuredScreenMode() {
+    const raw = process.env.NEGOTIATION_SCREEN_MODE;
+    if (raw === "shadow" || raw === "enforce" || raw === "off")
+        return raw;
+    return "off";
+}
+/**
+ * Structured screen decision — the outreach gate's verdict on whether this
+ * match is worth the client's name before any turn is exchanged.
+ */
+export const ScreenDecisionSchema = z.object({
+    decision: z.enum(["reach_out", "pass"]),
+    reasoning: z.string(),
+    /** Suggested opening angle for the outreach turn (only when reaching out). */
+    outreachAngle: z.string().nullable().optional(),
+    evidence: z.object({
+        /** How well the counterparty's context/premises fit the client's need. */
+        counterpartyPremiseFit: z.string(),
+        /** How the client's intents align with what the counterparty seeks. */
+        intentAlignment: z.string(),
+        /** Prior-negotiation memory signals (P5.3). Filled only when negotiator memory was injected into the screen prompt. */
+        memoryHints: z.string().nullable().optional(),
+    }),
+});
+/**
+ * Whether an enforce-mode outreach screen blocks a negotiation before any
+ * turn is exchanged. Shadow-mode pass decisions are recorded but never block.
+ * Failed-open rows are treated as reach_out regardless of `decision`.
+ */
+export function blocksNegotiationBeforeFirstTurn(decisionRecord, turnCount) {
+    if (!decisionRecord)
+        return false;
+    return (decisionRecord.mode === "enforce" &&
+        !decisionRecord.failedOpen &&
+        decisionRecord.decision === "pass" &&
+        turnCount === 0);
+}