@indexnetwork/protocol 21.0.0-rc.488.1 → 21.0.0-rc.490.1

package/dist/shared/schemas/negotiation-state.schema.d.ts

@@ -25,16 +25,99 @@ export declare const NEGOTIATION_CONSULTATION_REASONS: readonly ["unresolved_own
 export declare const NegotiationConsultationReasonSchema: z.ZodEnum<["unresolved_owner_constraint", "consequential_disclosure_permission", "repeated_non_convergence", "insufficient_commitment_authority"]>;
 export type NegotiationConsultationReason = z.infer<typeof NegotiationConsultationReasonSchema>;
 /**
- * Payload for a v2 `ask_user` action. Agents may choose only a closed reason;
- * disclosure subjects and question wording are always rendered by fixed
- * server templates and can never carry model-authored instructions.
+ * Payload for a v2 `ask_user` action.
+ *
+ * `reason` stays the closed enum it has always been: it is admission metadata
+ * for the deterministic consultation policy, not copy. `question` is the
+ * channel through which the user's own personal agent — the only thing that
+ * should be writing questions — hands over the question it authored from the
+ * negotiation it is actually having. Free-form keys beyond these two are still
+ * rejected by `.strict()`.
  */
 export declare const AskUserPayloadSchema: z.ZodObject<{
     reason: z.ZodEnum<["unresolved_owner_constraint", "consequential_disclosure_permission", "repeated_non_convergence", "insufficient_commitment_authority"]>;
+    /**
+     * The question the negotiating agent wrote, in the structured shape the UI
+     * already renders. Optional: v1 turns, external agents, and the existing
+     * enum-only path must all keep validating, so a payload of `{ reason }`
+     * alone stays byte-identical in and out.
+     *
+     * Declared `.nullable().optional()` (not bare `.optional()`) so the enclosing
+     * turn schemas survive OpenAI/OpenRouter strict structured-output conversion,
+     * which rejects optional-without-nullable fields — the same constraint
+     * documented on `QuestionSchema.evidence`. The `.transform()` normalizes an
+     * LLM-returned `null` back to `undefined`, so a null is never persisted and
+     * `null` and omitted read as absent identically downstream.
+     */
+    question: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        title: z.ZodString;
+        prompt: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            description: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            label: string;
+            description: string;
+        }, {
+            label: string;
+            description: string;
+        }>, "many">;
+        multiSelect: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        prompt: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        title: string;
+        multiSelect: boolean;
+    }, {
+        prompt: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        title: string;
+        multiSelect: boolean;
+    }>>>, {
+        prompt: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        title: string;
+        multiSelect: boolean;
+    } | undefined, {
+        prompt: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        title: string;
+        multiSelect: boolean;
+    } | null | undefined>;
 }, "strict", z.ZodTypeAny, {
     reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+    question?: {
+        prompt: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        title: string;
+        multiSelect: boolean;
+    } | undefined;
 }, {
     reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+    question?: {
+        prompt: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        title: string;
+        multiSelect: boolean;
+    } | null | undefined;
 }>;
 export type AskUserPayload = z.infer<typeof AskUserPayloadSchema>;
 export declare const NegotiationTurnSchema: z.ZodObject<{
@@ -68,10 +151,88 @@ export declare const NegotiationTurnSchema: z.ZodObject<{
     /** Present when action is `ask_user` (v2, P3.2). */
     askUser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         reason: z.ZodEnum<["unresolved_owner_constraint", "consequential_disclosure_permission", "repeated_non_convergence", "insufficient_commitment_authority"]>;
+        /**
+         * The question the negotiating agent wrote, in the structured shape the UI
+         * already renders. Optional: v1 turns, external agents, and the existing
+         * enum-only path must all keep validating, so a payload of `{ reason }`
+         * alone stays byte-identical in and out.
+         *
+         * Declared `.nullable().optional()` (not bare `.optional()`) so the enclosing
+         * turn schemas survive OpenAI/OpenRouter strict structured-output conversion,
+         * which rejects optional-without-nullable fields — the same constraint
+         * documented on `QuestionSchema.evidence`. The `.transform()` normalizes an
+         * LLM-returned `null` back to `undefined`, so a null is never persisted and
+         * `null` and omitted read as absent identically downstream.
+         */
+        question: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            title: z.ZodString;
+            prompt: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                description: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                label: string;
+                description: string;
+            }, {
+                label: string;
+                description: string;
+            }>, "many">;
+            multiSelect: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        }, {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        }>>>, {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        } | undefined, {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        } | null | undefined>;
     }, "strict", z.ZodTypeAny, {
         reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+        question?: {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        } | undefined;
     }, {
         reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+        question?: {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        } | null | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
     action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
@@ -85,6 +246,15 @@ export declare const NegotiationTurnSchema: z.ZodObject<{
     message?: string | null | undefined;
     askUser?: {
         reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+        question?: {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        } | undefined;
     } | null | undefined;
 }, {
     action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
@@ -98,6 +268,15 @@ export declare const NegotiationTurnSchema: z.ZodObject<{
     message?: string | null | undefined;
     askUser?: {
         reason: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority";
+        question?: {
+            prompt: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            title: string;
+            multiSelect: boolean;
+        } | null | undefined;
     } | null | undefined;
 }>;
 export type NegotiationTurn = z.infer<typeof NegotiationTurnSchema>;

package/dist/shared/schemas/negotiation-state.schema.js

@@ -4,6 +4,7 @@
  * LangGraph Annotation.Root stays in the domain file.
  */
 import { z } from "zod";
+import { StructuredQuestionSchema } from "./structured-question.schema.js";
 // ─── Zod schemas (available for runtime validation) ───────────────────────────
 /**
  * Union of every negotiation turn action across protocol versions.
@@ -29,12 +30,31 @@ export const NEGOTIATION_CONSULTATION_REASONS = [
 ];
 export const NegotiationConsultationReasonSchema = z.enum(NEGOTIATION_CONSULTATION_REASONS);
 /**
- * Payload for a v2 `ask_user` action. Agents may choose only a closed reason;
- * disclosure subjects and question wording are always rendered by fixed
- * server templates and can never carry model-authored instructions.
+ * Payload for a v2 `ask_user` action.
+ *
+ * `reason` stays the closed enum it has always been: it is admission metadata
+ * for the deterministic consultation policy, not copy. `question` is the
+ * channel through which the user's own personal agent — the only thing that
+ * should be writing questions — hands over the question it authored from the
+ * negotiation it is actually having. Free-form keys beyond these two are still
+ * rejected by `.strict()`.
  */
 export const AskUserPayloadSchema = z.object({
     reason: NegotiationConsultationReasonSchema,
+    /**
+     * The question the negotiating agent wrote, in the structured shape the UI
+     * already renders. Optional: v1 turns, external agents, and the existing
+     * enum-only path must all keep validating, so a payload of `{ reason }`
+     * alone stays byte-identical in and out.
+     *
+     * Declared `.nullable().optional()` (not bare `.optional()`) so the enclosing
+     * turn schemas survive OpenAI/OpenRouter strict structured-output conversion,
+     * which rejects optional-without-nullable fields — the same constraint
+     * documented on `QuestionSchema.evidence`. The `.transform()` normalizes an
+     * LLM-returned `null` back to `undefined`, so a null is never persisted and
+     * `null` and omitted read as absent identically downstream.
+     */
+    question: StructuredQuestionSchema.nullable().optional().transform((value) => value ?? undefined),
 }).strict();
 export const NegotiationTurnSchema = z.object({
     action: z.enum(NEGOTIATION_ACTIONS),

package/dist/shared/schemas/structured-question.schema.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+/**
+ * Canonical structured question shape: the title/prompt/options/multiSelect
+ * quartet every question renderer (frontend cards, MCP elicitation) consumes.
+ *
+ * It lives in `shared/` rather than inside `questions/` for the same reason as
+ * `underspecification.schema.ts`: more than one capability needs the shape.
+ * The questions capability owns question *generation* and extends this with its
+ * own provenance field; the negotiator only needs to hand over a question it
+ * authored (`AskUserPayloadSchema` in `negotiation-state.schema.ts`), and
+ * `shared/schemas` must not value-import a capability module to reach a shape.
+ *
+ * Field constraints are tuned for the renderer and are the single source of
+ * truth — `questions/question.schema.ts` re-exports rather than redeclares.
+ */
+export declare const QuestionOptionSchema: z.ZodObject<{
+    /** Display text. Suffix " (Recommended)" on the safest path; list it first. */
+    label: z.ZodString;
+    /** Explains the consequence of choosing this option, not just its definition. */
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    description: string;
+}, {
+    label: string;
+    description: string;
+}>;
+export declare const StructuredQuestionSchema: z.ZodObject<{
+    /** ≤12 chars. Noun of the decision domain — e.g. "Stage", "Timing", "Role". */
+    title: z.ZodString;
+    /** ≤2 sentences, ≤400 chars. Ends in a question mark. */
+    prompt: z.ZodString;
+    /** 2–4 options. No explicit "Other" — clients provide that automatically. */
+    options: z.ZodArray<z.ZodObject<{
+        /** Display text. Suffix " (Recommended)" on the safest path; list it first. */
+        label: z.ZodString;
+        /** Explains the consequence of choosing this option, not just its definition. */
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        description: string;
+    }, {
+        label: string;
+        description: string;
+    }>, "many">;
+    /** True when options are not mutually exclusive (priorities, bundles). */
+    multiSelect: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    options: {
+        label: string;
+        description: string;
+    }[];
+    title: string;
+    multiSelect: boolean;
+}, {
+    prompt: string;
+    options: {
+        label: string;
+        description: string;
+    }[];
+    title: string;
+    multiSelect: boolean;
+}>;
+export type QuestionOption = z.infer<typeof QuestionOptionSchema>;
+export type StructuredQuestion = z.infer<typeof StructuredQuestionSchema>;

package/dist/shared/schemas/structured-question.schema.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * Canonical structured question shape: the title/prompt/options/multiSelect
+ * quartet every question renderer (frontend cards, MCP elicitation) consumes.
+ *
+ * It lives in `shared/` rather than inside `questions/` for the same reason as
+ * `underspecification.schema.ts`: more than one capability needs the shape.
+ * The questions capability owns question *generation* and extends this with its
+ * own provenance field; the negotiator only needs to hand over a question it
+ * authored (`AskUserPayloadSchema` in `negotiation-state.schema.ts`), and
+ * `shared/schemas` must not value-import a capability module to reach a shape.
+ *
+ * Field constraints are tuned for the renderer and are the single source of
+ * truth — `questions/question.schema.ts` re-exports rather than redeclares.
+ */
+export const QuestionOptionSchema = z.object({
+    /** Display text. Suffix " (Recommended)" on the safest path; list it first. */
+    label: z.string().min(1).max(120),
+    /** Explains the consequence of choosing this option, not just its definition. */
+    description: z.string().min(1).max(280),
+});
+export const StructuredQuestionSchema = z.object({
+    /** ≤12 chars. Noun of the decision domain — e.g. "Stage", "Timing", "Role". */
+    title: z.string().min(1).max(12),
+    /** ≤2 sentences, ≤400 chars. Ends in a question mark. */
+    prompt: z.string().min(1).max(400),
+    /** 2–4 options. No explicit "Other" — clients provide that automatically. */
+    options: z.array(QuestionOptionSchema).min(2).max(4),
+    /** True when options are not mutually exclusive (priorities, bundles). */
+    multiSelect: z.boolean(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indexnetwork/protocol",
-  "version": "21.0.0-rc.488.1",
+  "version": "21.0.0-rc.490.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",