@indexnetwork/protocol 21.0.0-rc.490.1 → 21.1.0-rc.492.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/negotiations/negotiation.agent.d.ts

@@ -103,6 +103,7 @@ export interface IndexNegotiatorConfig {
      */
     turnTimeoutMs?: number;
 }
+export declare function resolveTurnTimeoutMs(override?: number): number;
 /**
  * Unified system negotiation agent that advocates for its user.
  * Adapts behavior based on turn position (first turn = propose, subsequent = respond).

package/dist/negotiations/negotiation.agent.js

@@ -113,7 +113,7 @@ const DEFAULT_TURN_TIMEOUT_MS = 15000;
 function isValidTimeoutMs(n) {
     return Number.isFinite(n) && n > 0 && n <= Number.MAX_SAFE_INTEGER;
 }
-function resolveTurnTimeoutMs(override) {
+export function resolveTurnTimeoutMs(override) {
     if (typeof override === "number" && isValidTimeoutMs(override))
         return override;
     const envValue = process.env.NEGOTIATOR_TURN_TIMEOUT_MS;

package/dist/negotiations/negotiation.graph.finalize.js

@@ -2,11 +2,12 @@
  * Negotiation graph, stage 4: persist the outcome and fan out follow-ups.
  */
 import { requestContext } from "../shared/observability/request-context.js";
-import { isRejectLikeAction, isTerminalAction } from "./negotiation.protocol.js";
+import { isRejectLikeAction, isTerminalAction, negotiationAskRoundsCap } from "./negotiation.protocol.js";
 import { blocksNegotiationBeforeFirstTurn } from "./negotiation.screen.js";
-import { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK } from './negotiation.question-safety.js';
+import { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK, isSafeAuthoredNegotiationQuestion } from './negotiation.question-safety.js';
+import { NEGOTIATION_PARK_REASONING } from './negotiation.stall-gap.js';
 import { isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
-import { finalizeLog, turnsFromMessages } from "./negotiation.graph.shared.js";
+import { countNegotiationAskRounds, finalizeLog, retrieveClientDm, turnsFromMessages } from "./negotiation.graph.shared.js";
 export async function finalizeNode(state, deps) {
     const traceEmitter = requestContext.getStore()?.traceEmitter;
     const emitWide = (event) => traceEmitter?.(event);
@@ -113,6 +114,131 @@ export async function finalizeNode(state, deps) {
                 ? { reason: "turn_cap" }
                 : {}),
     };
+    // Unconcluded end: no opportunity, no explicit reject, and turns actually
+    // happened — turn cap, timeout, or a plain stall. Feeds both the post-stall
+    // park below and the legacy questioner enqueue further down.
+    const endedUnconcluded = !hasOpportunity && !screenedOut && !isRejectLikeAction(lastTurn?.action) && state.turnCount > 0;
+    const stallReason = atCap
+        ? 'turn_cap'
+        : (state.error && /timeout/i.test(state.error))
+            ? 'timeout'
+            : 'stalled';
+    // ─── Post-stall park (conversational-questions plan) ──────────────────
+    // Instead of ending silently, an unconcluded negotiation parks carrying
+    // the ONE question that would let a retry conclude — authored by the
+    // negotiator from this negotiation's transcript and the signal's client
+    // DM, exactly the grounding the mid-flight consult uses. The gap is
+    // persisted as an `ask_user` message in the negotiation's own record: the
+    // parked negotiation is the only durable record of the information need,
+    // the same substrate the per-side ration reads, and an `ask_user` last
+    // message keeps the floor with the asking side on retry.
+    //
+    // Bounded per negotiation: past the ask-rounds cap the negotiation stalls
+    // TERMINALLY — no authoring call, no park — so two agents cannot
+    // ping-pong their humans indefinitely. Runs on continuations too (a
+    // resumed negotiation may park again); the cap is what bounds the loop.
+    //
+    // Every failure — authoring, safety gate, persistence — degrades to
+    // today's terminal stall. A park is additive state, never a new way for
+    // finalize to fail.
+    if (endedUnconcluded
+        && deps.stallGapAuthor
+        && state.opportunityId
+        && state.sourceIntentId
+        && state.indexContext.networkId) {
+        const askRounds = countNegotiationAskRounds(state.messages);
+        const askRoundsCap = negotiationAskRoundsCap();
+        if (askRounds >= askRoundsCap) {
+            finalizeLog.info('negotiation_ask_cap_terminal', {
+                taskId: state.taskId,
+                opportunityId: state.opportunityId,
+                askRounds,
+                askRoundsCap,
+                stallReason,
+            });
+            emitWide({
+                type: 'negotiation_ask_cap_terminal',
+                opportunityId: state.opportunityId,
+                askRounds,
+                askRoundsCap,
+            });
+        }
+        else {
+            try {
+                const clientDm = await retrieveClientDm(deps, state.sourceUser.id, state.sourceIntentId);
+                const parkIntent = state.sourceUser.intents.find((intent) => intent.id === state.sourceIntentId);
+                const gap = await deps.stallGapAuthor.author({
+                    userName: state.sourceUser.profile.name ?? 'your user',
+                    signal: parkIntent
+                        ? { title: parkIntent.title, description: parkIntent.description }
+                        : { title: 'Signal', description: 'the signal attached to this match' },
+                    seedReasoning: state.seedAssessment.reasoning,
+                    history,
+                    stallReason,
+                    ...(clientDm.length > 0 && { clientDm }),
+                });
+                // Same identifier-aware gate as the mid-flight authored question, with
+                // the same inputs in hand: the counterparty's name and the evaluator's
+                // reasoning. An unsafe question never parks — there is no enum-only
+                // downgrade here because a park without its gap records nothing.
+                const counterpartyName = state.candidateUser.profile?.name?.trim();
+                const seedReasoning = state.seedAssessment?.reasoning?.trim();
+                const safeGap = gap && isSafeAuthoredNegotiationQuestion(gap.question, {
+                    ...(counterpartyName ? { forbiddenIdentifiers: [counterpartyName] } : {}),
+                    ...(seedReasoning ? { forbiddenSourceText: [seedReasoning] } : {}),
+                });
+                if (safeGap) {
+                    const parkTurn = {
+                        action: 'ask_user',
+                        assessment: {
+                            reasoning: NEGOTIATION_PARK_REASONING,
+                            suggestedRoles: lastTurn?.assessment.suggestedRoles ?? { ownUser: 'peer', otherUser: 'peer' },
+                        },
+                        message: null,
+                        askUser: { reason: gap.reason, question: gap.question },
+                    };
+                    await deps.database.createMessage({
+                        conversationId: state.conversationId,
+                        senderId: `agent:${state.sourceUser.id}`,
+                        role: 'agent',
+                        parts: [{ kind: 'data', data: parkTurn }],
+                        taskId: state.taskId,
+                        ...(state.continuationExecution ? { continuationExecution: state.continuationExecution } : {}),
+                    });
+                    finalizeLog.info('negotiation_parked', {
+                        taskId: state.taskId,
+                        opportunityId: state.opportunityId,
+                        recipientUserId: state.sourceUser.id,
+                        recipientIntentId: state.sourceIntentId,
+                        askRounds: askRounds + 1,
+                        askRoundsCap,
+                        stallReason,
+                    });
+                    emitWide({
+                        type: 'negotiation_parked',
+                        opportunityId: state.opportunityId,
+                        negotiationConversationId: state.conversationId,
+                        askRounds: askRounds + 1,
+                        askRoundsCap,
+                        stallReason,
+                    });
+                }
+                else if (gap) {
+                    finalizeLog.warn('Dropping unsafe post-stall gap question; negotiation stalls without a park', {
+                        taskId: state.taskId,
+                        opportunityId: state.opportunityId,
+                    });
+                }
+            }
+            catch (err) {
+                finalizeLog.error('Failed to park stalled negotiation with its gap', {
+                    taskId: state.taskId,
+                    opportunityId: state.opportunityId,
+                    error: err,
+                });
+            }
+        }
+    }
     try {
         await deps.database.updateTaskState(state.taskId, "completed", undefined, state.continuationExecution);
         await deps.database.createArtifact({
@@ -226,12 +352,9 @@ export async function finalizeNode(state, deps) {
     }
     // Enqueue question generation for stalled/capped negotiations (not accepted or explicitly rejected).
     // Require turnCount > 0 so early init/turn errors don't enqueue with empty context.
-    if (!hasOpportunity && !isRejectLikeAction(lastTurn?.action) && state.turnCount > 0 && state.opportunityId && state.sourceIntentId && state.indexContext.networkId && deps.questionerEnqueue && !state.continuationExecution) {
-        const stallReason = atCap
-            ? 'turn_cap'
-            : (state.error && /timeout/i.test(state.error))
-                ? 'timeout'
-                : 'stalled';
+    // Kept alongside the post-stall park above until the conversational-questions
+    // delivery lane retires the blind questioner path.
+    if (endedUnconcluded && state.opportunityId && state.sourceIntentId && state.indexContext.networkId && deps.questionerEnqueue && !state.continuationExecution) {
         const userContext = (await deps.database.getUserContext(state.sourceUser.id, null))?.text ?? '';
         const sourceIntent = state.sourceUser.intents.find((intent) => intent.id === state.sourceIntentId);
         deps.questionerEnqueue({

package/dist/negotiations/negotiation.graph.js

@@ -8,6 +8,7 @@
 import { StateGraph } from "@langchain/langgraph";
 import { NegotiationGraphState } from "./negotiation.state.js";
 import { IndexNegotiator } from "./negotiation.agent.js";
+import { NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
 import { blocksNegotiationBeforeFirstTurn, NegotiationScreener } from "./negotiation.screen.js";
 import { configuredScreenMode } from "./negotiation.screen.contracts.js";
 import { isTerminalAction } from "./negotiation.protocol.js";
@@ -32,6 +33,7 @@ export class NegotiationGraphFactory {
             memoryRetrieve,
             clientDmRetrieve,
             systemAgent: new IndexNegotiator(),
+            stallGapAuthor: new NegotiationStallGapAuthor(),
             screener: new NegotiationScreener(),
         };
     }

package/dist/negotiations/negotiation.graph.shared.d.ts

@@ -16,6 +16,7 @@ import type { QuestionerEnqueueFn } from "../questions/question.module.js";
 import type { ReflectEnqueueFn } from "./negotiation.reflect.js";
 import type { NegotiatorMemoryEntry, NegotiatorMemoryRetrieveFn, NegotiatorMemoryScope } from "./negotiation.memory.js";
 import type { NegotiatorClientDmMessage, NegotiatorClientDmRetrieveFn } from "./negotiation.client-dm.js";
+import type { NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
 import { type AttributedPriorDialogue, type TaskAttribution } from './negotiation.attribution.js';
 /** The graph's channel state, as every node sees it. */
 export type NegotiationState = typeof NegotiationGraphState.State;
@@ -35,6 +36,8 @@ export interface NegotiationGraphDeps {
     clientDmRetrieve?: NegotiatorClientDmRetrieveFn;
     /** In-process negotiator used when no personal agent answers. */
     systemAgent: IndexNegotiator;
+    /** Authors the post-stall gap question at finalize (park-on-stall). */
+    stallGapAuthor?: NegotiationStallGapAuthor;
     /** Outreach gate for fresh negotiations. */
     screener: NegotiationScreener;
 }
@@ -60,6 +63,20 @@ export declare function hasPriorAskUser(messages: Array<{
     senderId: string;
     parts: unknown[];
 }>, userId: string): boolean;
+/**
+ * How many ask rounds this negotiation has already spent, BOTH sides combined.
+ * A round is one persisted `ask_user` park — a mid-flight client consultation
+ * or a post-stall park — each of which suspends the negotiation on a human
+ * answer. Same substrate as {@link hasPriorAskUser} (the negotiation's own
+ * message record, spanning all of its sessions), read negotiation-wide rather
+ * than per side: the cap this feeds bounds the park → answer → resume loop for
+ * the negotiation as a whole, so two agents cannot ping-pong their humans
+ * indefinitely.
+ */
+export declare function countNegotiationAskRounds(messages: Array<{
+    senderId: string;
+    parts: unknown[];
+}>): number;
 /**
  * P5.3 memory retrieval — never throws, never blocks a negotiation. The
  * injected fn already resolves [] when NEGOTIATOR_MEMORY_INJECT is off;

package/dist/negotiations/negotiation.graph.shared.js

@@ -23,6 +23,15 @@ export function turnsFromMessages(messages) {
     })
         .filter(Boolean);
 }
+/** Sender ids of every persisted `ask_user` park in this negotiation's messages. */
+function askUserSenderIds(messages) {
+    return messages
+        .filter((m) => {
+        const dataPart = m.parts.find((p) => p.kind === "data");
+        return dataPart?.data?.action === "ask_user";
+    })
+        .map((m) => m.senderId);
+}
 /**
  * Whether `userId`'s side has already spent its one `ask_user` client
  * consultation in THIS negotiation (P3.2 rationing: max one per negotiation per
@@ -32,13 +41,20 @@ export function turnsFromMessages(messages) {
  * counterparty does not.
  */
 export function hasPriorAskUser(messages, userId) {
-    const sender = `agent:${userId}`;
-    return messages.some((m) => {
-        if (m.senderId !== sender)
-            return false;
-        const dataPart = m.parts.find((p) => p.kind === "data");
-        return dataPart?.data?.action === "ask_user";
-    });
+    return askUserSenderIds(messages).includes(`agent:${userId}`);
+}
+/**
+ * How many ask rounds this negotiation has already spent, BOTH sides combined.
+ * A round is one persisted `ask_user` park — a mid-flight client consultation
+ * or a post-stall park — each of which suspends the negotiation on a human
+ * answer. Same substrate as {@link hasPriorAskUser} (the negotiation's own
+ * message record, spanning all of its sessions), read negotiation-wide rather
+ * than per side: the cap this feeds bounds the park → answer → resume loop for
+ * the negotiation as a whole, so two agents cannot ping-pong their humans
+ * indefinitely.
+ */
+export function countNegotiationAskRounds(messages) {
+    return askUserSenderIds(messages).length;
 }
 /**
  * P5.3 memory retrieval — never throws, never blocks a negotiation. The

package/dist/negotiations/negotiation.graph.turn.js

@@ -2,13 +2,13 @@
  * Negotiation graph, stage 3: one negotiator turn.
  */
 import { requestContext } from "../shared/observability/request-context.js";
-import { allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, fallbackActionFor, rejectActionFor } from "./negotiation.protocol.js";
+import { allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, fallbackActionFor, negotiationAskRoundsCap, rejectActionFor } from "./negotiation.protocol.js";
 import { assessConsultationEligibility, consultationPromptFor, negotiationConsultationPolicyMode } from "./negotiation.consultation-policy.js";
 import { blocksNegotiationBeforeFirstTurn } from "./negotiation.screen.js";
 import { assessDeadlock, configuredDeadlockShiftEnabled, configuredDeadlockThreshold } from "./negotiation.deadlock.js";
 import { NEGOTIATION_QUESTION_GENERIC_COUNTERPARTY, NEGOTIATION_QUESTION_GENERIC_NETWORK, isSafeAuthoredNegotiationQuestion, negotiationQuestionSettlementId } from './negotiation.question-safety.js';
 import { isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
-import { buildAttributedDialogue, hasPriorAskUser, memoryQueryText, retrieveClientDm, retrieveMemory, turnLog, turnsFromMessages } from "./negotiation.graph.shared.js";
+import { buildAttributedDialogue, countNegotiationAskRounds, hasPriorAskUser, memoryQueryText, retrieveClientDm, retrieveMemory, turnLog, turnsFromMessages } from "./negotiation.graph.shared.js";
 export async function turnNode(state, deps) {
     const traceEmitter = requestContext.getStore()?.traceEmitter;
     // Local helper to emit events whose shape is wider than the declared
@@ -38,6 +38,12 @@ export async function turnNode(state, deps) {
         // against), v2 non-final non-opening turn, and this side's one client
         // consultation not yet spent (rationing). Shadow is observational and
         // must preserve this legacy path byte-for-byte except for telemetry.
+        //
+        // The negotiation-wide ask-rounds cap reads the same message substrate
+        // as the per-side ration. It cannot bind on mid-flight consults alone
+        // (one per side < default cap); it exists so post-stall parks — which
+        // also persist `ask_user` messages — count against the same budget,
+        // and a negotiation near its cap cannot spend a further round here.
         const policyMode = negotiationConsultationPolicyMode();
         const askUserAvailable = version === 'v2'
             && !isFinalTurn
@@ -48,7 +54,8 @@ export async function turnNode(state, deps) {
             && !!ownIntentId
             && !!state.indexContext.networkId
             && !(state.turnCount === 0 && !state.isContinuation)
-            && !hasPriorAskUser(state.messages, ownUser.id);
+            && !hasPriorAskUser(state.messages, ownUser.id)
+            && countNegotiationAskRounds(state.messages) < negotiationAskRoundsCap();
         // ─── Deadlock detection → persuasion→bargaining stance (IND-428) ──────
         // Deterministic trailing-run inspection of the persisted history — no
         // LLM in the decision. Gated on the strict default-off flag AND v2,

package/dist/negotiations/negotiation.module.d.ts

@@ -13,7 +13,10 @@ export { NegotiationScreener } from "./negotiation.screen.js";
 export type { ChatReflectionInput, DistilledMemory, NegotiationReflectionInput, NegotiationReflectJobData, ReflectEnqueueFn, ReflectionTranscriptEntry, } from "./negotiation.reflect.js";
 export type { NegotiationCandidate, OnNegotiationResolved } from "./negotiation.graph.js";
 export type { NegotiationDigest } from "./insight.generator.js";
-export { ASK_USER_LOCK_SLACK_MS, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { ASK_USER_LOCK_SLACK_MS, DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, negotiationAskRoundsCap, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { countNegotiationAskRounds } from "./negotiation.graph.shared.js";
+export { NEGOTIATION_PARK_REASONING, NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
+export type { NegotiationStallGap, NegotiationStallReason, StallGapAuthorInput } from "./negotiation.stall-gap.js";
 export { HERMES_OWNER_DIRECTIVE, HERMES_SHARED_MESSAGE_TEMPLATES, HermesNegotiationActionSchema, HermesNegotiationResponseSchema, HermesOwnerDirectiveSchema, HermesRoleAlignmentSchema, allowedHermesActionsFor, buildHermesNegotiationTurn, } from "./negotiation.hermes-contract.js";
 export { DEFAULT_NEGOTIATION_MAX_TURNS, isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
 export { expectedNegotiationSpeaker } from "./negotiation.expected-speaker.js";

package/dist/negotiations/negotiation.module.js

@@ -10,7 +10,9 @@ export { negotiateCandidates, NegotiationGraphFactory } from "./negotiation.grap
 export { NegotiationInsightsGenerator } from "./insight.generator.js";
 export { NegotiationReflector } from "./negotiation.reflect.js";
 export { NegotiationScreener } from "./negotiation.screen.js";
-export { ASK_USER_LOCK_SLACK_MS, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { ASK_USER_LOCK_SLACK_MS, DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP, allowedActionsFor, askUserAnswerWindowMs, configuredAskUserEnabled, isRejectLikeAction, isTerminalAction, negotiationAskRoundsCap, readProtocolVersion, resolveSeat, seatViolationMessage, } from "./negotiation.protocol.js";
+export { countNegotiationAskRounds } from "./negotiation.graph.shared.js";
+export { NEGOTIATION_PARK_REASONING, NegotiationStallGapAuthor } from "./negotiation.stall-gap.js";
 export { HERMES_OWNER_DIRECTIVE, HERMES_SHARED_MESSAGE_TEMPLATES, HermesNegotiationActionSchema, HermesNegotiationResponseSchema, HermesOwnerDirectiveSchema, HermesRoleAlignmentSchema, allowedHermesActionsFor, buildHermesNegotiationTurn, } from "./negotiation.hermes-contract.js";
 export { DEFAULT_NEGOTIATION_MAX_TURNS, isNegotiationTurnCapReached } from "./negotiation.turn-cap.js";
 export { expectedNegotiationSpeaker } from "./negotiation.expected-speaker.js";

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

@@ -972,6 +972,20 @@ export declare function configuredProtocolVersion(): NegotiationProtocolVersion;
  * the same single switch.
  */
 export declare function configuredAskUserEnabled(): boolean;
+/**
+ * Default per-negotiation ask cap: total client-consultation rounds (mid-flight
+ * `ask_user` pauses and post-stall parks, both sides combined) before the
+ * negotiation stalls terminally instead of parking again. Three admits one
+ * post-stall park even after each side has spent its one mid-flight consult.
+ */
+export declare const DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP = 3;
+/**
+ * Per-negotiation ask cap, overridable via `NEGOTIATION_ASK_ROUNDS_CAP`.
+ * Invalid or non-positive values fall back to the default — zero is not an
+ * off switch here; the cap exists so two agents cannot ping-pong their humans
+ * indefinitely. It tunes the bound, it does not gate the behaviour.
+ */
+export declare function negotiationAskRoundsCap(): number;
 /** Default answer window for a paused `ask_user` negotiation: 24 hours. */
 export declare const DEFAULT_ASK_USER_WINDOW_MS: number;
 /**

package/dist/negotiations/negotiation.protocol.js

@@ -155,6 +155,28 @@ export function configuredProtocolVersion() {
 export function configuredAskUserEnabled() {
     return process.env.NEGOTIATION_ASK_USER_ENABLED === "true";
 }
+/**
+ * Default per-negotiation ask cap: total client-consultation rounds (mid-flight
+ * `ask_user` pauses and post-stall parks, both sides combined) before the
+ * negotiation stalls terminally instead of parking again. Three admits one
+ * post-stall park even after each side has spent its one mid-flight consult.
+ */
+export const DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP = 3;
+/**
+ * Per-negotiation ask cap, overridable via `NEGOTIATION_ASK_ROUNDS_CAP`.
+ * Invalid or non-positive values fall back to the default — zero is not an
+ * off switch here; the cap exists so two agents cannot ping-pong their humans
+ * indefinitely. It tunes the bound, it does not gate the behaviour.
+ */
+export function negotiationAskRoundsCap() {
+    const raw = process.env.NEGOTIATION_ASK_ROUNDS_CAP;
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isInteger(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_NEGOTIATION_ASK_ROUNDS_CAP;
+}
 /** Default answer window for a paused `ask_user` negotiation: 24 hours. */
 export const DEFAULT_ASK_USER_WINDOW_MS = 24 * 60 * 60 * 1000;
 /**

package/dist/negotiations/negotiation.stall-gap.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Post-stall gap authoring (conversational-questions plan).
+ *
+ * When a negotiation ends unconcluded — no opportunity, no explicit reject:
+ * turn cap, timeout, or stall — the finalize node asks the negotiator for the
+ * ONE question whose answer would let a retry conclude, and parks the
+ * negotiation carrying that gap as an `ask_user` message in its own record.
+ * This module owns that single extra model call.
+ *
+ * Grounding is exactly what mid-flight authoring (P3.2 / IND-401 A2H) uses:
+ * this negotiation's transcript, plus the client's own negotiator DM for the
+ * signal when the caller retrieved one. Same non-naming and non-echo rules;
+ * the caller re-checks the output with `isSafeAuthoredNegotiationQuestion`
+ * (identifiers in hand) before persisting anything.
+ *
+ * Fail-open contract: any model failure, timeout, or invalid output resolves
+ * to null — the negotiation then stalls exactly as it did before this feature,
+ * never half-parks.
+ */
+import { createStructuredModel } from "../shared/agent/model.config.js";
+import { type StructuredQuestion } from "../shared/schemas/structured-question.schema.js";
+import { type NegotiationConsultationReason } from "../shared/schemas/negotiation-state.schema.js";
+import { type NegotiatorClientDmMessage } from "./negotiation.client-dm.js";
+import type { NegotiationTurn } from "./negotiation.state.js";
+/**
+ * Fixed transcript reasoning for a post-stall park turn. Deliberately not
+ * model-authored: assessment reasoning enters the shared A2A record, and the
+ * park's "why" already lives in the guarded question itself — a second,
+ * unguarded free-text channel would reopen the leak surface the question gate
+ * closes.
+ */
+export declare const NEGOTIATION_PARK_REASONING = "Negotiation parked pending the client's answer.";
+/** Why the negotiation failed to conclude, as finalize classified it. */
+export type NegotiationStallReason = "turn_cap" | "timeout" | "stalled";
+/** The authored gap: what a retry needs from the client, and why the pause is warranted. */
+export interface NegotiationStallGap {
+    reason: NegotiationConsultationReason;
+    question: StructuredQuestion;
+}
+export interface StallGapAuthorInput {
+    /** Display name of the client the question is addressed to. */
+    userName: string;
+    /** The client's signal this negotiation was about. */
+    signal: {
+        title: string;
+        description: string;
+    };
+    /** Why the match was suggested (evaluator output; context, never copy). */
+    seedReasoning: string;
+    /** This negotiation's full transcript, oldest first. */
+    history: NegotiationTurn[];
+    stallReason: NegotiationStallReason;
+    /** Recent excerpt of the client's negotiator DM for this signal, most recent last. */
+    clientDm?: NegotiatorClientDmMessage[];
+}
+export interface NegotiationStallGapAuthorConfig {
+    /** Hard ceiling on the model round-trip, in ms. Same resolution as the negotiator turn timeout. */
+    timeoutMs?: number;
+}
+/**
+ * Authors the post-stall gap. One instance lives in the graph's dependency bag
+ * beside `systemAgent`; the finalize node calls it at most once per stalled
+ * session.
+ */
+export declare class NegotiationStallGapAuthor {
+    private readonly timeoutMs;
+    constructor(config?: NegotiationStallGapAuthorConfig);
+    /**
+     * @returns The authored gap, or null when there is none to ask — the model
+     *          said so, produced invalid output after a retry, or failed. The
+     *          caller treats every null identically: terminal stall, no park.
+     */
+    author(input: StallGapAuthorInput): Promise<NegotiationStallGap | null>;
+    /**
+     * Raw structured-model round trip. Split out as a seam so tests can drive
+     * the validate→retry→null loop without a live provider — same pattern as
+     * `IndexNegotiator.callModel`.
+     */
+    protected callModel(model: ReturnType<typeof createStructuredModel>, chatMessages: Array<{
+        role: string;
+        content: string;
+    }>): Promise<unknown>;
+}

package/dist/negotiations/negotiation.stall-gap.js

@@ -0,0 +1,152 @@
+/**
+ * Post-stall gap authoring (conversational-questions plan).
+ *
+ * When a negotiation ends unconcluded — no opportunity, no explicit reject:
+ * turn cap, timeout, or stall — the finalize node asks the negotiator for the
+ * ONE question whose answer would let a retry conclude, and parks the
+ * negotiation carrying that gap as an `ask_user` message in its own record.
+ * This module owns that single extra model call.
+ *
+ * Grounding is exactly what mid-flight authoring (P3.2 / IND-401 A2H) uses:
+ * this negotiation's transcript, plus the client's own negotiator DM for the
+ * signal when the caller retrieved one. Same non-naming and non-echo rules;
+ * the caller re-checks the output with `isSafeAuthoredNegotiationQuestion`
+ * (identifiers in hand) before persisting anything.
+ *
+ * Fail-open contract: any model failure, timeout, or invalid output resolves
+ * to null — the negotiation then stalls exactly as it did before this feature,
+ * never half-parks.
+ */
+import { z } from "zod";
+import { createStructuredModel } from "../shared/agent/model.config.js";
+import { invokeWithAbortSignal } from "../shared/agent/model-signal.js";
+import { StructuredQuestionSchema } from "../shared/schemas/structured-question.schema.js";
+import { NegotiationConsultationReasonSchema } from "../shared/schemas/negotiation-state.schema.js";
+import { renderNegotiatorClientDmSection } from "./negotiation.client-dm.js";
+import { resolveTurnTimeoutMs } from "./negotiation.agent.js";
+import { protocolLogger } from "../shared/observability/protocol.logger.js";
+const stallGapLog = protocolLogger("NegotiationStallGapAuthor");
+/**
+ * Fixed transcript reasoning for a post-stall park turn. Deliberately not
+ * model-authored: assessment reasoning enters the shared A2A record, and the
+ * park's "why" already lives in the guarded question itself — a second,
+ * unguarded free-text channel would reopen the leak surface the question gate
+ * closes.
+ */
+export const NEGOTIATION_PARK_REASONING = "Negotiation parked pending the client's answer.";
+const STALL_REASON_LABELS = {
+    turn_cap: "the turn limit was reached without agreement",
+    timeout: "the negotiation timed out",
+    stalled: "the exchange stalled without reaching a conclusion",
+};
+/**
+ * Structured output for the gap call. `hasGap: false` is a first-class answer:
+ * when no single client answer would change a retry's outcome, the negotiation
+ * must stall terminally rather than park on a filler question. Nullable
+ * declarations mirror `AskUserPayloadSchema.question` — strict structured-output
+ * conversion rejects optional-without-nullable, and a returned null reads as
+ * absent.
+ */
+const StallGapOutputSchema = z.object({
+    hasGap: z.boolean(),
+    reason: NegotiationConsultationReasonSchema.nullable().optional().transform((value) => value ?? undefined),
+    question: StructuredQuestionSchema.nullable().optional().transform((value) => value ?? undefined),
+});
+const SYSTEM_PROMPT = `You are the Index Negotiator, an AI agent acting on behalf of {userName}. A negotiation you conducted for them about a potential connection has just ended without conclusion: {stallReasonLabel}.
+
+Your job now is a single decision: is there ONE piece of information only {userName} holds whose answer would let a retry of this negotiation reach a conclusion? Read the exchange below and judge where it actually stuck.
+
+- If no single answer from {userName} would change a retry's outcome — the match is simply weak, the counterparty is the blocker, or the stall had nothing to do with missing input from {userName} — set hasGap to false and omit the question. Do not invent a question to have something to ask; asking costs {userName} attention and pauses nothing useful.
+- If yes, set hasGap to true and author the question:
+  - reason: exactly one closed server category recording WHY the pause is warranted: "unresolved_owner_constraint" | "consequential_disclosure_permission" | "repeated_non_convergence" | "insufficient_commitment_authority". It is not the wording {userName} sees.
+  - title: at most 12 characters — a noun for the decision domain, e.g. "Stage", "Timing", "Budget", "Scope".
+  - prompt: at most 2 sentences and 400 characters, ending in a question mark. Ask about the specific thing that was actually stuck in this negotiation, in {userName}'s own terms, grounded in the exchange below. Never a generic template.
+  - options: 2–4 of {userName}'s real decision options. Each label at most 120 characters; each description at most 280 characters, stating the CONSEQUENCE of choosing that option — what the retry would do with it — not what it means. Never add an "Other" option; clients provide a free-text fallback automatically.
+  - multiSelect: true ONLY when the options are not mutually exclusive; false for a single either/or decision.
+  - Do not name, quote, or describe the counterparty. {userName} can read the transcript, but the question itself must stand on its own without their identity or profile in it.
+  - Do NOT reference internal system details like scores, pre-screens, or evaluator outputs.{dmGroundingRule}`;
+/**
+ * Appended only when the call actually carries a client-DM excerpt, mirroring
+ * `ASK_USER_DM_GROUNDING_RULE`: a call with no DM must not carry a rule that
+ * dangles with nothing in the prompt to check against.
+ */
+const DM_GROUNDING_RULE = `
+  - Ground the question in your conversation with {userName} about this signal (shown below) as well as in the exchange. Do NOT ask what they have already answered there: if their own words settle the point, there is no gap on it. Use their terms for the thing at stake — the words, numbers, and framing they used, not your paraphrase of them.`;
+function formatTurnLine(turn, index) {
+    const msgPart = turn.message ? ` — message: ${turn.message}` : "";
+    return `Turn ${index + 1}: ${turn.action} — reasoning: ${turn.assessment.reasoning}${msgPart}`;
+}
+/**
+ * Authors the post-stall gap. One instance lives in the graph's dependency bag
+ * beside `systemAgent`; the finalize node calls it at most once per stalled
+ * session.
+ */
+export class NegotiationStallGapAuthor {
+    constructor(config) {
+        this.timeoutMs = resolveTurnTimeoutMs(config?.timeoutMs);
+    }
+    /**
+     * @returns The authored gap, or null when there is none to ask — the model
+     *          said so, produced invalid output after a retry, or failed. The
+     *          caller treats every null identically: terminal stall, no park.
+     */
+    async author(input) {
+        const clientDm = input.clientDm ?? [];
+        const model = createStructuredModel("negotiator", StallGapOutputSchema, { name: "negotiation_stall_gap" });
+        const systemPrompt = SYSTEM_PROMPT
+            .replace("{stallReasonLabel}", STALL_REASON_LABELS[input.stallReason])
+            .replace("{dmGroundingRule}", clientDm.length > 0 ? DM_GROUNDING_RULE : "")
+            .replace(/{userName}/g, input.userName);
+        const transcript = input.history.length > 0
+            ? `\n\nNegotiation transcript:\n${input.history.map(formatTurnLine).join("\n")}`
+            : "";
+        const userMessage = `{userName}'s signal under negotiation:
+- ${input.signal.title}: ${input.signal.description}
+
+Why this match was suggested: ${input.seedReasoning}${transcript}${renderNegotiatorClientDmSection(clientDm, input.userName)}
+
+Decide whether one question to {userName} would let a retry conclude, and author it if so.`.replace(/{userName}/g, input.userName);
+        const chatMessages = [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userMessage },
+        ];
+        try {
+            // Same validate → retry-once → give-up loop as the negotiator turn,
+            // except giving up resolves to null (terminal stall) instead of a
+            // fallback action — there is no conservative fallback question.
+            for (let attempt = 0; attempt < 2; attempt++) {
+                const result = await this.callModel(model, chatMessages);
+                const parsed = StallGapOutputSchema.safeParse(result);
+                if (!parsed.success) {
+                    stallGapLog.warn("Stall-gap output failed schema validation", {
+                        attempt: attempt + 1,
+                        issues: parsed.error.issues.map((issue) => issue.message).slice(0, 3),
+                    });
+                    continue;
+                }
+                if (!parsed.data.hasGap)
+                    return null;
+                if (!parsed.data.question || !parsed.data.reason) {
+                    stallGapLog.warn("Stall-gap output claimed a gap without question or reason", { attempt: attempt + 1 });
+                    continue;
+                }
+                return { reason: parsed.data.reason, question: parsed.data.question };
+            }
+            return null;
+        }
+        catch (err) {
+            stallGapLog.warn("Stall-gap authoring failed; negotiation stalls without a park", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    }
+    /**
+     * Raw structured-model round trip. Split out as a seam so tests can drive
+     * the validate→retry→null loop without a live provider — same pattern as
+     * `IndexNegotiator.callModel`.
+     */
+    async callModel(model, chatMessages) {
+        return invokeWithAbortSignal(model, chatMessages, AbortSignal.timeout(this.timeoutMs));
+    }
+}

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.492.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": [