@indexnetwork/protocol 4.5.0-rc.335.1 → 4.5.0-rc.337.1

package/dist/negotiation/negotiation.protocol.d.ts

@@ -48,6 +48,17 @@ export declare const InitiatorTurnSchema: z.ZodObject<{
         };
     }>;
     message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Present when action is `ask_user` (v2, P3.2). */
+    askUser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        disclosureSubject: z.ZodString;
+        draftQuestion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     action: "counter" | "question" | "outreach" | "withdraw";
     assessment: {
@@ -58,6 +69,10 @@ export declare const InitiatorTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }, {
     action: "counter" | "question" | "outreach" | "withdraw";
     assessment: {
@@ -68,6 +83,10 @@ export declare const InitiatorTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }>;
 /** Counterparty seat, non-final turn: the only seat that can accept. */
 export declare const CounterpartyTurnSchema: z.ZodObject<{
@@ -98,6 +117,17 @@ export declare const CounterpartyTurnSchema: z.ZodObject<{
         };
     }>;
     message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Present when action is `ask_user` (v2, P3.2). */
+    askUser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        disclosureSubject: z.ZodString;
+        draftQuestion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     action: "accept" | "counter" | "question" | "decline";
     assessment: {
@@ -108,6 +138,10 @@ export declare const CounterpartyTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }, {
     action: "accept" | "counter" | "question" | "decline";
     assessment: {
@@ -118,6 +152,10 @@ export declare const CounterpartyTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }>;
 /** Initiator seat, final allowed turn: commit to walking away or leave the door open. */
 export declare const FinalInitiatorTurnSchema: z.ZodObject<{
@@ -148,6 +186,17 @@ export declare const FinalInitiatorTurnSchema: z.ZodObject<{
         };
     }>;
     message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Present when action is `ask_user` (v2, P3.2). */
+    askUser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        disclosureSubject: z.ZodString;
+        draftQuestion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     action: "counter" | "withdraw";
     assessment: {
@@ -158,6 +207,10 @@ export declare const FinalInitiatorTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }, {
     action: "counter" | "withdraw";
     assessment: {
@@ -168,6 +221,10 @@ export declare const FinalInitiatorTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }>;
 /** Counterparty seat, final allowed turn: must decide. */
 export declare const FinalCounterpartyTurnSchema: z.ZodObject<{
@@ -198,6 +255,17 @@ export declare const FinalCounterpartyTurnSchema: z.ZodObject<{
         };
     }>;
     message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Present when action is `ask_user` (v2, P3.2). */
+    askUser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        disclosureSubject: z.ZodString;
+        draftQuestion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     action: "accept" | "decline";
     assessment: {
@@ -208,6 +276,10 @@ export declare const FinalCounterpartyTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }, {
     action: "accept" | "decline";
     assessment: {
@@ -218,6 +290,148 @@ export declare const FinalCounterpartyTurnSchema: z.ZodObject<{
         };
     };
     message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
+}>;
+/** Initiator seat, non-final turn, with the client-consult pause available. */
+export declare const InitiatorAskUserTurnSchema: z.ZodObject<{
+    action: z.ZodEnum<["outreach", "counter", "question", "withdraw", "ask_user"]>;
+    assessment: z.ZodObject<{
+        reasoning: z.ZodString;
+        suggestedRoles: z.ZodObject<{
+            ownUser: z.ZodEnum<["agent", "patient", "peer"]>;
+            otherUser: z.ZodEnum<["agent", "patient", "peer"]>;
+        }, "strip", z.ZodTypeAny, {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        }, {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    }, {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    }>;
+    message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Present when action is `ask_user` (v2, P3.2). */
+    askUser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        disclosureSubject: z.ZodString;
+        draftQuestion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    action: "counter" | "question" | "outreach" | "withdraw" | "ask_user";
+    assessment: {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    };
+    message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
+}, {
+    action: "counter" | "question" | "outreach" | "withdraw" | "ask_user";
+    assessment: {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    };
+    message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
+}>;
+/** Counterparty seat, non-final turn, with the client-consult pause available. */
+export declare const CounterpartyAskUserTurnSchema: z.ZodObject<{
+    action: z.ZodEnum<["accept", "decline", "counter", "question", "ask_user"]>;
+    assessment: z.ZodObject<{
+        reasoning: z.ZodString;
+        suggestedRoles: z.ZodObject<{
+            ownUser: z.ZodEnum<["agent", "patient", "peer"]>;
+            otherUser: z.ZodEnum<["agent", "patient", "peer"]>;
+        }, "strip", z.ZodTypeAny, {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        }, {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    }, {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    }>;
+    message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Present when action is `ask_user` (v2, P3.2). */
+    askUser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        disclosureSubject: z.ZodString;
+        draftQuestion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }, {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    action: "accept" | "counter" | "question" | "decline" | "ask_user";
+    assessment: {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    };
+    message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
+}, {
+    action: "accept" | "counter" | "question" | "decline" | "ask_user";
+    assessment: {
+        reasoning: string;
+        suggestedRoles: {
+            ownUser: "agent" | "patient" | "peer";
+            otherUser: "agent" | "patient" | "peer";
+        };
+    };
+    message?: string | null | undefined;
+    askUser?: {
+        disclosureSubject: string;
+        draftQuestion?: string | null | undefined;
+    } | null | undefined;
 }>;
 /**
  * The set of actions a given seat may submit under a given protocol version.
@@ -225,7 +439,7 @@ export declare const FinalCounterpartyTurnSchema: z.ZodObject<{
  * v1 ignores the seat entirely (legacy symmetric vocabulary) so pre-v2
  * negotiations behave exactly as before.
  */
-export declare function allowedActionsFor(version: NegotiationProtocolVersion, seat: NegotiationSeat, isFinalTurn?: boolean): readonly NegotiationAction[];
+export declare function allowedActionsFor(version: NegotiationProtocolVersion, seat: NegotiationSeat, isFinalTurn?: boolean, opts?: AskUserOpts): readonly NegotiationAction[];
 /**
  * Zod turn schema for a system-agent turn, selected by version + seat +
  * final-turn flag. v1 returns the legacy schemas (seat-agnostic); v2 returns
@@ -238,7 +452,19 @@ export declare function allowedActionsFor(version: NegotiationProtocolVersion, s
 export declare function turnSchemaFor(version: NegotiationProtocolVersion, seat: NegotiationSeat, isFinalTurn: boolean, v1Schemas: {
     system: z.ZodTypeAny;
     final: z.ZodTypeAny;
-}): z.ZodTypeAny;
+}, opts?: AskUserOpts): z.ZodTypeAny;
+/**
+ * Opt-in extension of the seat vocabulary with the `ask_user` client-consult
+ * pause (P3.2). Never granted on final-cap turns (the final turn must decide)
+ * and never under v1. Callers pass `{ askUser: true }` only when the full
+ * pause loop is available on their surface: the ask-user feature flag is on,
+ * a questioner enqueue and an answer-window timer are wired, the negotiation
+ * has an opportunity to resume against, and the acting side has not already
+ * consumed its one client question for this negotiation (rationing).
+ */
+export interface AskUserOpts {
+    askUser?: boolean;
+}
 /** Terminal actions end the negotiation immediately. */
 export declare function isTerminalAction(action: string | undefined | null): boolean;
 /** Reject-like actions map the opportunity to `rejected` (v1 reject, v2 withdraw/decline). */
@@ -269,6 +495,28 @@ export declare function readProtocolVersion(metadata: {
  * v2 is opt-in per environment, and rolling back is the same single switch.
  */
 export declare function configuredProtocolVersion(): NegotiationProtocolVersion;
+/**
+ * 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 declare function configuredAskUserEnabled(): boolean;
+/** Default answer window for a paused `ask_user` negotiation: 24 hours. */
+export declare const DEFAULT_ASK_USER_WINDOW_MS: number;
+/**
+ * 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 declare function askUserAnswerWindowMs(): number;
+/**
+ * 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 declare const ASK_USER_LOCK_SLACK_MS: number;
 /**
  * Resolve the seat of `userId` on a negotiation task.
  *

package/dist/negotiation/negotiation.protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"negotiation.protocol.d.ts","sourceRoot":"/","sources":["negotiation/negotiation.protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAsBpI,kGAAkG;AAClG,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA8D,CAAC;AAE/F,wEAAwE;AACxE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA2D,CAAC;AAE/F,yFAAyF;AACzF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAsC,CAAC;AAE5E,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAoC,CAAC;AAW7E;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,eAAe,EACrB,WAAW,UAAQ,GAClB,SAAS,iBAAiB,EAAE,CAI9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE;IAAE,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,UAAU,CAAA;CAAE,GACvD,CAAC,CAAC,UAAU,CAId;AAID,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAE3E;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,OAAO,GACnB,iBAAiB,CAInB;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAC7B,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,eAAe,GACpB,iBAAiB,CAGnB;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GACzD,0BAA0B,GAAG,IAAI,CAGnC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,0BAA0B,CAEtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GACjF,eAAe,CAQjB;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAGR"}
+{"version":3,"file":"negotiation.protocol.d.ts","sourceRoot":"/","sources":["negotiation/negotiation.protocol.ts"],"names":[],"mappings":"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"}

package/dist/negotiation/negotiation.protocol.js

@@ -18,6 +18,7 @@
  * `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(),
@@ -31,6 +32,8 @@ function turnSchema(actions) {
         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 ─────────────────────────────────────────────
@@ -42,6 +45,14 @@ export const CounterpartyTurnSchema = turnSchema(["accept", "decline", "counter"
 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"];
@@ -49,18 +60,22 @@ 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) {
+export function allowedActionsFor(version, seat, isFinalTurn = false, opts) {
     if (version !== "v2")
         return isFinalTurn ? V1_FINAL_ACTIONS : V1_ACTIONS;
-    if (seat === "initiator")
-        return isFinalTurn ? V2_FINAL_INITIATOR_ACTIONS : V2_INITIATOR_ACTIONS;
-    return isFinalTurn ? V2_FINAL_COUNTERPARTY_ACTIONS : V2_COUNTERPARTY_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 +
@@ -71,12 +86,14 @@ export function allowedActionsFor(version, seat, isFinalTurn = false) {
  * 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) {
+export function turnSchemaFor(version, seat, isFinalTurn, v1Schemas, opts) {
     if (version !== "v2")
         return isFinalTurn ? v1Schemas.final : v1Schemas.system;
-    if (seat === "initiator")
-        return isFinalTurn ? FinalInitiatorTurnSchema : InitiatorTurnSchema;
-    return isFinalTurn ? FinalCounterpartyTurnSchema : CounterpartyTurnSchema;
+    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. */
@@ -127,6 +144,38 @@ export function readProtocolVersion(metadata) {
 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.
  *

package/dist/negotiation/negotiation.protocol.js.map

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