@indexnetwork/protocol 21.0.0-rc.489.1 → 21.1.0-rc.491.1

package/dist/shared/schemas/question-block.fixture.js

@@ -0,0 +1,39 @@
+export const questionProseFixture = [
+    "I moved three conversations forward on your search for a technical co-founder.",
+    "Two of them are waiting on details only you can give — answer here and I will",
+    "pick the negotiations back up.",
+].join("\n");
+export const questionBlockFixture = {
+    version: 1,
+    questions: [
+        {
+            prompt: "Both counterparts asked about equity: what range are you prepared to offer a founding engineer?",
+            opportunityId: "0b0e8a9c-6d3f-4d6a-9f2e-1c5b7a4d8e01",
+            alsoUnblocks: ["7f3d2c1b-8a90-4e5f-b6c7-d8e9f0a1b2c3"],
+        },
+        {
+            prompt: "The Berlin robotics lab wants to know whether you can be on-site one week per month.",
+            opportunityId: "4a5b6c7d-8e9f-4a1b-8c2d-3e4f5a6b7c8d",
+        },
+    ],
+};
+export const questionMessageFixture = `${questionProseFixture}
+
+\`\`\`index-questions
+{
+  "version": 1,
+  "questions": [
+    {
+      "prompt": "Both counterparts asked about equity: what range are you prepared to offer a founding engineer?",
+      "opportunityId": "0b0e8a9c-6d3f-4d6a-9f2e-1c5b7a4d8e01",
+      "alsoUnblocks": [
+        "7f3d2c1b-8a90-4e5f-b6c7-d8e9f0a1b2c3"
+      ]
+    },
+    {
+      "prompt": "The Berlin robotics lab wants to know whether you can be on-site one week per month.",
+      "opportunityId": "4a5b6c7d-8e9f-4a1b-8c2d-3e4f5a6b7c8d"
+    }
+  ]
+}
+\`\`\``;

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

@@ -0,0 +1,111 @@
+/**
+ * The question block: the rendering contract between the negotiator's
+ * question-message and the web client's steps UI, and the routing contract
+ * for answers (docs/plans/2026-08-18-conversational-questions.md).
+ *
+ * The block is a *view* of the currently-parked negotiations for one intent
+ * scope, regenerated fresh on every change — it is not a persistence schema
+ * and must never grow state (answered flags, timestamps, question ids).
+ * A question's identity is its primary negotiation reference: the id of the
+ * opportunity row the negotiation runs on. Task re-resolution from that row
+ * is server-side and never encoded here — deliberately, because a snapshotted
+ * task id would go stale: answer routing branches on what it re-resolves
+ * (an `input_required` task → mid-flight consult, answered via the exact
+ * continuation's successor task; a completed task on a stalled opportunity
+ * with a trailing ask_user gap → post-stall park, answered via a retry).
+ *
+ * This module must stay browser-safe: it may import zod and nothing else.
+ * It is exposed to the web client via the `@indexnetwork/protocol/question-block`
+ * subpath export (see STABILITY.md).
+ */
+import { z } from "zod";
+/** Info string of the fenced section that carries the block in a message body. */
+export declare const QUESTION_BLOCK_MARKER = "index-questions";
+/** Bump when the block shape changes; parsers fail closed on unknown versions. */
+export declare const QUESTION_BLOCK_VERSION = 1;
+export declare const QuestionBlockQuestionSchema: z.ZodObject<{
+    /** Agent-authored question text, rendered as one step. */
+    prompt: z.ZodString;
+    /** Primary negotiation this question unparks; doubles as the question's identity. */
+    opportunityId: z.ZodString;
+    /** Further negotiations parked on the same gap that this answer also unparks. */
+    alsoUnblocks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    prompt: string;
+    opportunityId: string;
+    alsoUnblocks?: string[] | undefined;
+}, {
+    prompt: string;
+    opportunityId: string;
+    alsoUnblocks?: string[] | undefined;
+}>;
+export type QuestionBlockQuestion = z.infer<typeof QuestionBlockQuestionSchema>;
+export declare const QuestionBlockSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    questions: z.ZodArray<z.ZodObject<{
+        /** Agent-authored question text, rendered as one step. */
+        prompt: z.ZodString;
+        /** Primary negotiation this question unparks; doubles as the question's identity. */
+        opportunityId: z.ZodString;
+        /** Further negotiations parked on the same gap that this answer also unparks. */
+        alsoUnblocks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        prompt: string;
+        opportunityId: string;
+        alsoUnblocks?: string[] | undefined;
+    }, {
+        prompt: string;
+        opportunityId: string;
+        alsoUnblocks?: string[] | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    questions: {
+        prompt: string;
+        opportunityId: string;
+        alsoUnblocks?: string[] | undefined;
+    }[];
+    version: 1;
+}, {
+    questions: {
+        prompt: string;
+        opportunityId: string;
+        alsoUnblocks?: string[] | undefined;
+    }[];
+    version: 1;
+}>, {
+    questions: {
+        prompt: string;
+        opportunityId: string;
+        alsoUnblocks?: string[] | undefined;
+    }[];
+    version: 1;
+}, {
+    questions: {
+        prompt: string;
+        opportunityId: string;
+        alsoUnblocks?: string[] | undefined;
+    }[];
+    version: 1;
+}>;
+export type QuestionBlock = z.infer<typeof QuestionBlockSchema>;
+/** A parsed question-message: the agent's prose and the block that followed it. */
+export interface ParsedQuestionMessage {
+    prose: string;
+    block: QuestionBlock;
+}
+/**
+ * Embed a block after the agent's prose. The block is always the terminal
+ * section of the body: prose, a blank line, then a fenced section whose info
+ * string is the marker. The fence is lengthened past any backtick run in the
+ * payload so the payload can never close it early.
+ *
+ * Throws on a block that fails the schema — serializing an invalid block is a
+ * producer bug, not a rendering condition.
+ */
+export declare function serializeQuestionMessage(prose: string, block: QuestionBlock): string;
+/**
+ * Extract the block from a message body. Fails closed: any body that does not
+ * end in exactly one well-formed, schema-valid block returns null, and the
+ * caller renders the whole body as plain text — never a broken steps UI.
+ */
+export declare function parseQuestionMessage(body: string): ParsedQuestionMessage | null;

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

@@ -0,0 +1,124 @@
+/**
+ * The question block: the rendering contract between the negotiator's
+ * question-message and the web client's steps UI, and the routing contract
+ * for answers (docs/plans/2026-08-18-conversational-questions.md).
+ *
+ * The block is a *view* of the currently-parked negotiations for one intent
+ * scope, regenerated fresh on every change — it is not a persistence schema
+ * and must never grow state (answered flags, timestamps, question ids).
+ * A question's identity is its primary negotiation reference: the id of the
+ * opportunity row the negotiation runs on. Task re-resolution from that row
+ * is server-side and never encoded here — deliberately, because a snapshotted
+ * task id would go stale: answer routing branches on what it re-resolves
+ * (an `input_required` task → mid-flight consult, answered via the exact
+ * continuation's successor task; a completed task on a stalled opportunity
+ * with a trailing ask_user gap → post-stall park, answered via a retry).
+ *
+ * This module must stay browser-safe: it may import zod and nothing else.
+ * It is exposed to the web client via the `@indexnetwork/protocol/question-block`
+ * subpath export (see STABILITY.md).
+ */
+import { z } from "zod";
+/** Info string of the fenced section that carries the block in a message body. */
+export const QUESTION_BLOCK_MARKER = "index-questions";
+/** Bump when the block shape changes; parsers fail closed on unknown versions. */
+export const QUESTION_BLOCK_VERSION = 1;
+/**
+ * A negotiation reference: the id of the opportunity row the negotiation runs
+ * on. There is no negotiations table — opportunity id is the durable identity
+ * used by every negotiation binding (see NegotiationQuestionProvenanceSchema).
+ */
+const NegotiationRefSchema = z.string().uuid();
+export const QuestionBlockQuestionSchema = z.object({
+    /** Agent-authored question text, rendered as one step. */
+    prompt: z.string().min(1).max(2000),
+    /** Primary negotiation this question unparks; doubles as the question's identity. */
+    opportunityId: NegotiationRefSchema,
+    /** Further negotiations parked on the same gap that this answer also unparks. */
+    alsoUnblocks: z.array(NegotiationRefSchema).max(8).optional(),
+}).strict();
+export const QuestionBlockSchema = z.object({
+    version: z.literal(QUESTION_BLOCK_VERSION),
+    questions: z.array(QuestionBlockQuestionSchema).min(1).max(20),
+}).strict().superRefine((block, ctx) => {
+    // Identity is the negotiation ref, so a ref may appear exactly once in the
+    // whole block — a duplicate would make answer routing ambiguous.
+    const seen = new Set();
+    block.questions.forEach((question, questionIndex) => {
+        const refs = [question.opportunityId, ...(question.alsoUnblocks ?? [])];
+        refs.forEach((ref, refIndex) => {
+            if (seen.has(ref)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: refIndex === 0
+                        ? ["questions", questionIndex, "opportunityId"]
+                        : ["questions", questionIndex, "alsoUnblocks", refIndex - 1],
+                    message: `negotiation ref ${ref} appears more than once in the block`,
+                });
+            }
+            seen.add(ref);
+        });
+    });
+});
+const openFencePattern = new RegExp(`^(\`{3,})${QUESTION_BLOCK_MARKER}[ \\t]*\\r?$`, "m");
+function longestBacktickRun(text) {
+    let longest = 0;
+    for (const run of text.match(/`+/g) ?? [])
+        longest = Math.max(longest, run.length);
+    return longest;
+}
+/**
+ * Embed a block after the agent's prose. The block is always the terminal
+ * section of the body: prose, a blank line, then a fenced section whose info
+ * string is the marker. The fence is lengthened past any backtick run in the
+ * payload so the payload can never close it early.
+ *
+ * Throws on a block that fails the schema — serializing an invalid block is a
+ * producer bug, not a rendering condition.
+ */
+export function serializeQuestionMessage(prose, block) {
+    const payload = JSON.stringify(QuestionBlockSchema.parse(block), null, 2);
+    const fence = "`".repeat(Math.max(3, longestBacktickRun(payload) + 1));
+    const trimmedProse = prose.trimEnd();
+    const fenced = `${fence}${QUESTION_BLOCK_MARKER}\n${payload}\n${fence}`;
+    return trimmedProse.length > 0 ? `${trimmedProse}\n\n${fenced}` : fenced;
+}
+/**
+ * Extract the block from a message body. Fails closed: any body that does not
+ * end in exactly one well-formed, schema-valid block returns null, and the
+ * caller renders the whole body as plain text — never a broken steps UI.
+ */
+export function parseQuestionMessage(body) {
+    // Anchor on the last marker fence so prose that merely mentions the marker
+    // earlier in the body cannot shadow the real block.
+    let open = null;
+    const searchPattern = new RegExp(openFencePattern.source, "gm");
+    for (let match = searchPattern.exec(body); match; match = searchPattern.exec(body)) {
+        open = match;
+    }
+    if (!open)
+        return null;
+    const fenceLength = open[1].length;
+    const payloadStart = open.index + open[0].length + 1; // past the fence line's newline
+    if (payloadStart > body.length)
+        return null;
+    const closePattern = new RegExp(`^\`{${fenceLength}}[ \\t]*\\r?$`, "m");
+    const close = closePattern.exec(body.slice(payloadStart));
+    if (!close)
+        return null;
+    // The block must terminate the message: nothing but whitespace may follow.
+    const afterClose = body.slice(payloadStart + close.index + close[0].length);
+    if (afterClose.trim().length > 0)
+        return null;
+    let parsedPayload;
+    try {
+        parsedPayload = JSON.parse(body.slice(payloadStart, payloadStart + close.index));
+    }
+    catch {
+        return null;
+    }
+    const block = QuestionBlockSchema.safeParse(parsedPayload);
+    if (!block.success)
+        return null;
+    return { prose: body.slice(0, open.index).trimEnd(), block: block.data };
+}

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.489.1",
+  "version": "21.1.0-rc.491.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -8,6 +8,14 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./question-block": {
+      "types": "./dist/shared/schemas/question-block.schema.d.ts",
+      "import": "./dist/shared/schemas/question-block.schema.js"
+    },
+    "./question-block/fixture": {
+      "types": "./dist/shared/schemas/question-block.fixture.d.ts",
+      "import": "./dist/shared/schemas/question-block.fixture.js"
     }
   },
   "files": [