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

package/CHANGELOG.md

@@ -20,6 +20,27 @@ went 6.7.1 → 8.0.2 with no 7.x in between because the whole 7.x line shipped a
 prereleases between the two promotions. To track every change, read `rc`; to
 pin a supported release, use `latest`.
 
+## 21.1.0 - 2026-08-18
+
+### Added
+
+- The **question block contract** for conversational questions
+  (`docs/plans/2026-08-18-conversational-questions.md`):
+  `QuestionBlockSchema`, `QuestionBlockQuestionSchema`,
+  `parseQuestionMessage`, `serializeQuestionMessage`,
+  `QUESTION_BLOCK_MARKER`, `QUESTION_BLOCK_VERSION` and the
+  `QuestionBlock`/`QuestionBlockQuestion`/`ParsedQuestionMessage` types.
+  The block is the rendering contract embedded as a terminal
+  ` ```index-questions ` fenced section in the negotiator's question-message;
+  the parser fails closed (malformed → `null` → render as plain text), and a
+  question's identity is its primary `opportunityId` ref (negotiations have
+  no table of their own) — there are no question ids and no block-level state.
+- First package **subpath exports**, `@indexnetwork/protocol/question-block`
+  and `.../question-block/fixture`, so the browser client can import the
+  contract (and its canonical fixture) without pulling the node-only package
+  root into a bundle. STABILITY.md now documents browser-safe subpaths as part
+  of the public contract.
+
 ## 21.0.0 - 2026-08-17
 
 ### Removed

package/STABILITY.md

@@ -7,8 +7,16 @@ change. It is the reference behind the tier annotations in `src/index.ts`.
 
 ## The public contract
 
-- The **only** supported entry point is the package root:
-  `import { ... } from "@indexnetwork/protocol"`.
+- The supported entry points are the package root:
+  `import { ... } from "@indexnetwork/protocol"` — and the **browser-safe
+  subpaths** listed in `package.json` `exports` (as of 21.1.0:
+  `@indexnetwork/protocol/question-block` and
+  `@indexnetwork/protocol/question-block/fixture`). A browser-safe subpath
+  exposes one shared-schema module whose only runtime dependency is `zod`, for
+  consumers (the web client) that cannot load the node-only package root. The
+  schema module's symbols are also re-exported from the root (the fixture is
+  subpath-only, to keep test data out of the runtime barrel), and the subpaths
+  carry the Stable tier.
 - Deep imports (`@indexnetwork/protocol/dist/...` or `/src/...`) are **not** part
   of the contract and may change or disappear in any release — do not rely on them.
 - The contract is exactly the set of symbols re-exported from `src/index.ts`.

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export type { PendingQuestionSummary } from "./shared/schemas/pending-question.s
 export { McpApiKeyMetadataSchema } from "./shared/schemas/mcp-auth.schema.js";
 export type { McpAuthInput, McpResolvedIdentity, } from "./shared/schemas/mcp-auth.schema.js";
 export type { DiscoveryNegotiation } from "./shared/schemas/discovery-question.schema.js";
+export { QUESTION_BLOCK_MARKER, QUESTION_BLOCK_VERSION, QuestionBlockSchema, QuestionBlockQuestionSchema, parseQuestionMessage, serializeQuestionMessage, type QuestionBlock, type QuestionBlockQuestion, type ParsedQuestionMessage, } from "./shared/schemas/question-block.schema.js";
 export type { NetworkAssignmentMetadata } from "./shared/schemas/network-assignment.schema.js";
 export { DEFAULT_NETWORK_ASSIGNMENT_THRESHOLD, resolveAssignmentNetworkScope, buildNetworkAssignmentDecision } from "./shared/assignment/network-assignment.policy.js";
 export { ChatGraphFactory } from "./agents/agent.module.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export { SYSTEM_AGENT_IDS } from './agents/agent.module.js';
 export { ChatContextDigestSchema } from "./shared/schemas/chat-context.schema.js";
 export { NegotiationQuestionCandidateSchema, } from "./questions/question.module.js";
 export { McpApiKeyMetadataSchema } from "./shared/schemas/mcp-auth.schema.js";
+export { QUESTION_BLOCK_MARKER, QUESTION_BLOCK_VERSION, QuestionBlockSchema, QuestionBlockQuestionSchema, parseQuestionMessage, serializeQuestionMessage, } from "./shared/schemas/question-block.schema.js";
 export { DEFAULT_NETWORK_ASSIGNMENT_THRESHOLD, resolveAssignmentNetworkScope, buildNetworkAssignmentDecision } from "./shared/assignment/network-assignment.policy.js";
 // ─── Graph factories ──────────────────────────────────────────────────────────
 export { ChatGraphFactory } from "./agents/agent.module.js";

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

@@ -0,0 +1,12 @@
+/**
+ * Canonical question-message fixture for the question block contract.
+ *
+ * `questionMessageFixture` is a literal — not derived from the serializer — so
+ * a serializer change that would alter the wire format breaks the spec loudly.
+ * The web client's steps-UI tests should import this via
+ * `@indexnetwork/protocol/question-block/fixture` instead of minting their own.
+ */
+import type { QuestionBlock } from "./question-block.schema.js";
+export declare const questionProseFixture: string;
+export declare const questionBlockFixture: QuestionBlock;
+export declare const questionMessageFixture: string;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indexnetwork/protocol",
-  "version": "21.0.0-rc.490.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": [