@indexnetwork/protocol 6.12.0-rc.403.1 → 6.13.22-rc.405.1

package/dist/questions/application/question.agent.js

@@ -0,0 +1,139 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/**
+ * questions/application/question.agent — QuestionerAgent.
+ *
+ * Stateless, mode-driven agent that generates structured decision questions
+ * from arbitrary protocol contexts.
+ *
+ * Follows the IndexNegotiator pattern: constructor takes optional config,
+ * single public `invoke()` method receives the full context per call.
+ * The LLM model is bound once at construction; the preset (system prompt +
+ * builder) is selected per invocation based on `input.mode`.
+ *
+ * IND-547: canonical home — previously questioner/questioner.agent.ts.
+ * Legacy path is a thin compatibility shim pointing here.
+ */
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { QuestionGeneratorResponseSchema } from "../domain/question.schema.js";
+import { createStructuredModel } from "../../shared/agent/model.config.js";
+import { invokeWithAbortSignal } from "../../shared/agent/model-signal.js";
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+import { Timed } from "../../shared/observability/performance.js";
+import { getPreset } from "./question.presets.js";
+import { isValidQuestionerInputContract } from "./question.input.js";
+const logger = protocolLogger("QuestionerAgent");
+/** Maximum same-strategy questions allowed in a single emission. */
+const MAX_SAME_STRATEGY = 2;
+/**
+ * Stateless question-generation agent. Accepts a `QuestionerInput` envelope,
+ * selects the preset for the given mode, invokes the LLM, and applies
+ * guardrails (dedup + strategy diversity).
+ */
+export class QuestionerAgent {
+    constructor(config) {
+        this.model = createStructuredModel("questioner", QuestionGeneratorResponseSchema, {
+            name: "clarifying_questions",
+        }, config?.modelConfig);
+    }
+    /**
+     * Generate up to 3 decision questions from the given input.
+     *
+     * @param input  Envelope with mode, userId, source info, and mode-specific context.
+     * @param options.signal  Optional AbortSignal to cancel the in-flight LLM call.
+     * @returns A result with parallel questions[] and strategies[] arrays,
+     *   or null when generation failed, guardrails dropped all candidates,
+     *   the LLM threw, or the call was aborted.
+     */
+    async invoke(input, options) {
+        if (!isValidQuestionerInputContract(input)) {
+            logger.warn('QuestionerAgent rejected invalid mode/purpose/context contract', { mode: input.mode });
+            return null;
+        }
+        const preset = getPreset(input.mode, input.purpose);
+        const userMessage = preset.buildPrompt(input.context);
+        let raw;
+        try {
+            raw = await invokeWithAbortSignal(this.model, [new SystemMessage(preset.systemPrompt), new HumanMessage(userMessage)], options?.signal);
+        }
+        catch (err) {
+            const aborted = options?.signal?.aborted ?? false;
+            if (aborted) {
+                logger.info("QuestionerAgent aborted by signal", {
+                    mode: input.mode,
+                    reason: options?.signal?.reason instanceof Error
+                        ? options.signal.reason.message
+                        : String(options?.signal?.reason ?? "unknown"),
+                });
+            }
+            else {
+                logger.warn("QuestionerAgent LLM call failed", {
+                    mode: input.mode,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return null;
+        }
+        const parsed = QuestionGeneratorResponseSchema.safeParse(raw);
+        if (!parsed.success) {
+            logger.warn("QuestionerAgent parse failed", {
+                mode: input.mode,
+                error: parsed.error.message,
+            });
+            return null;
+        }
+        const filtered = applyGuardrails(parsed.data.questions);
+        if (filtered.length === 0)
+            return null;
+        return {
+            questions: filtered.map(stripInternalMetadata),
+            strategies: filtered.map((q) => q.strategy),
+            underspecificationTypes: filtered.map((q) => q.underspecificationType),
+        };
+    }
+}
+__decorate([
+    Timed(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], QuestionerAgent.prototype, "invoke", null);
+// --- Guardrails ---------------------------------------------------------------
+function applyGuardrails(questions) {
+    const dedupedByTitle = dedupByTitle(questions);
+    return enforceStrategyDiversity(dedupedByTitle);
+}
+function dedupByTitle(questions) {
+    const seen = new Set();
+    const out = [];
+    for (const q of questions) {
+        if (seen.has(q.title))
+            continue;
+        seen.add(q.title);
+        out.push(q);
+    }
+    return out;
+}
+function enforceStrategyDiversity(questions) {
+    const counts = new Map();
+    const out = [];
+    for (const q of questions) {
+        const n = counts.get(q.strategy) ?? 0;
+        if (n >= MAX_SAME_STRATEGY)
+            continue;
+        counts.set(q.strategy, n + 1);
+        out.push(q);
+    }
+    return out;
+}
+function stripInternalMetadata(q) {
+    const { strategy: _strategy, underspecificationType: _underspecificationType, ...publicShape } = q;
+    return publicShape;
+}

package/dist/questions/application/question.ask.tool.d.ts

@@ -0,0 +1,12 @@
+import type { DefineTool } from "../../shared/agent/tool.helpers.js";
+import type { AskUserQuestionToolDeps } from "../ports/question.tools.port.js";
+import { QuestionerAgent } from "./question.agent.js";
+/** Test seam: replace or reset the module-level QuestionerAgent singleton. */
+export declare function setQuestionerAgentForTesting(agent: QuestionerAgent | null): void;
+/**
+ * Creates the chat-only `ask_user_question` tool.
+ *
+ * @param defineTool - Tool factory provided by the composition root.
+ * @param deps       - Shared tool dependencies; requires `chatQuestions`.
+ */
+export declare function createAskUserQuestionTools(defineTool: DefineTool, deps: AskUserQuestionToolDeps): readonly [any];

package/dist/questions/application/question.ask.tool.js

@@ -0,0 +1,300 @@
+/**
+ * questions/application/question.ask.tool — foreground adapter: chat ask_user_question tool.
+ *
+ * Blocking mid-conversation questions for the chat orchestrator
+ * (AskUserQuestion-style human-in-the-loop).
+ *
+ * Flow (hybrid authoring):
+ * 1. The orchestrator states what it needs to learn (`purpose`) plus optional
+ *    draft questions.
+ * 2. QuestionerAgent (mode `chat`) refines that into polished structured
+ *    questions, grounded in the recent conversation excerpt and the user's
+ *    global context.
+ * 3. Questions are persisted (`questions` table, mode `chat`,
+ *    `conversationId = sessionId`) via the injected {@link ChatQuestionsHost}.
+ * 4. A `user_question` trace event streams the persisted questions to the
+ *    frontend, which renders them inline while the turn stays open.
+ * 5. The tool blocks on `awaitAnswers` until the user answers/dismisses
+ *    through the questions REST endpoints, the wait budget elapses, or the
+ *    run is aborted. Answers come back as the tool result so the model
+ *    continues the SAME turn.
+ *
+ * On timeout the questions remain `pending`: they survive reloads via the
+ * conversation-linked question fetch, and a later answer re-enters the chat
+ * as a new user turn (frontend responsibility).
+ *
+ * Foreground adapter: registered by `createChatTools` only when
+ * `deps.chatQuestions` is provided — never part of the MCP tool registry
+ * (MCP clients have their own elicitation surface).
+ *
+ * IND-547: canonical home — previously questioner/questioner.ask.tool.ts.
+ * Legacy path is a thin compatibility shim pointing here.
+ */
+import { z } from "zod";
+import { error, success } from "../../shared/agent/tool.helpers.js";
+import { requestContext } from "../../shared/observability/request-context.js";
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+import { QuestionerAgent } from "./question.agent.js";
+import { chatQuestionWaitTimeoutMs } from "./question.env.js";
+const logger = protocolLogger("AskUserQuestionTool");
+/** Heartbeat interval while blocked, so SSE transports do not idle out. */
+const WAIT_HEARTBEAT_MS = 15000;
+/** Messages included in the conversation excerpt fed to the QuestionerAgent. */
+const EXCERPT_MESSAGE_COUNT = 10;
+/**
+ * Fetch window for the excerpt. Host adapters return the FIRST N messages
+ * (ascending) when a limit is passed, so we fetch a wide window and keep the
+ * tail to get the most recent exchange.
+ */
+const EXCERPT_FETCH_LIMIT = 100;
+/** Max characters per message inside the excerpt. */
+const EXCERPT_MESSAGE_CHARS = 400;
+// Lazy singleton — construction binds the LLM once; invocations are stateless.
+let questionerAgent = null;
+function getQuestionerAgent() {
+    if (!questionerAgent)
+        questionerAgent = new QuestionerAgent();
+    return questionerAgent;
+}
+/** Test seam: replace or reset the module-level QuestionerAgent singleton. */
+export function setQuestionerAgentForTesting(agent) {
+    questionerAgent = agent;
+}
+const draftQuestionSchema = z.object({
+    prompt: z
+        .string()
+        .min(5)
+        .max(400)
+        .describe("The question to ask, ending in a question mark. Self-contained plain language."),
+    options: z
+        .array(z.string().min(1).max(120))
+        .min(2)
+        .max(4)
+        .optional()
+        .describe("2-4 mutually distinct answer options. Omit to let the question generator derive them."),
+    multiSelect: z
+        .boolean()
+        .optional()
+        .describe("True when several options can be picked together (priorities, bundles)."),
+});
+/**
+ * Build a fallback Question directly from an orchestrator draft when the
+ * QuestionerAgent produced nothing. Requires the draft to carry options.
+ */
+function questionFromDraft(draft, index) {
+    if (!draft.options || draft.options.length < 2)
+        return null;
+    return {
+        title: `Question ${index + 1}`,
+        prompt: draft.prompt.slice(0, 400),
+        options: draft.options.slice(0, 4).map((label) => ({
+            label: label.slice(0, 120),
+            description: label.slice(0, 280),
+        })),
+        multiSelect: draft.multiSelect ?? false,
+    };
+}
+/**
+ * Creates the chat-only `ask_user_question` tool.
+ *
+ * @param defineTool - Tool factory provided by the composition root.
+ * @param deps       - Shared tool dependencies; requires `chatQuestions`.
+ */
+export function createAskUserQuestionTools(defineTool, deps) {
+    const askUserQuestion = defineTool({
+        name: "ask_user_question",
+        description: "Ask the user 1-3 structured clarifying questions and WAIT for their answer before continuing. " +
+            "The conversation pauses: the user sees interactive question cards inline and your turn resumes " +
+            "with their selections as the tool result.\n\n" +
+            "**Use when** a decision materially changes what you do next — before an expensive operation " +
+            "(discovery, creating an intent from ambiguous input), when facing meaningfully different " +
+            "directions, or when one concrete missing detail (timing, scope, budget, format) blocks progress.\n\n" +
+            "**Do not use** for facts already visible in the conversation or profile, procedural " +
+            "confirmations (\"Should I proceed?\"), or open-ended questions better asked in your response text.\n\n" +
+            "**Input:** `purpose` states what you need to learn and why. Optionally propose `questions` " +
+            "drafts (prompt + 2-4 options); a question generator refines wording and option quality.\n\n" +
+            "**Returns:** One entry per question with `status` (`answered`/`dismissed`/`timeout`) and the " +
+            "user's `selectedOptions`/`freeText`. On `timeout` the questions stay visible in the " +
+            "conversation — acknowledge briefly and end your turn; do NOT repeat the questions in text.",
+        querySchema: z.object({
+            purpose: z
+                .string()
+                .min(10)
+                .max(600)
+                .describe("What you need to learn from the user and why it changes what you do next."),
+            questions: z
+                .array(draftQuestionSchema)
+                .min(1)
+                .max(3)
+                .optional()
+                .describe("Draft questions to ask. The question generator polishes them before display."),
+        }),
+        handler: async ({ context, query }) => {
+            const host = deps.chatQuestions;
+            if (!host) {
+                return error("Interactive questions are not available in this environment. Ask the user directly in your response text instead.");
+            }
+            if (context.isMcp || !context.sessionId) {
+                return error("Interactive questions require a live chat session. Ask the user directly in your response text instead.");
+            }
+            const store = requestContext.getStore();
+            const emit = store?.traceEmitter;
+            const signal = store?.abortSignal;
+            if (!emit) {
+                return error("Interactive questions require a streaming chat turn. Ask the user directly in your response text instead.");
+            }
+            const sessionId = context.sessionId;
+            // ── 1. Gather grounding context ────────────────────────────────────
+            const [conversationExcerpt, userContext] = await Promise.all([
+                loadConversationExcerpt(deps, sessionId),
+                deps.getUserContextText?.(context.userId).catch(() => "") ?? Promise.resolve(""),
+            ]);
+            // ── 2. Generate polished questions (hybrid: drafts + QuestionerAgent) ──
+            const chatContext = {
+                purpose: query.purpose,
+                ...(query.questions?.length ? { draftQuestions: query.questions } : {}),
+                ...(conversationExcerpt ? { conversationExcerpt } : {}),
+                ...(userContext ? { userContext } : {}),
+            };
+            let generated = null;
+            try {
+                generated = await getQuestionerAgent().invoke({
+                    mode: "chat",
+                    userId: context.userId,
+                    sourceType: "conversation",
+                    sourceId: sessionId,
+                    context: chatContext,
+                    conversationId: sessionId,
+                }, signal ? { signal } : undefined);
+            }
+            catch (err) {
+                logger.warn("QuestionerAgent invocation failed", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            let finalQuestions;
+            let strategies;
+            let underspecificationTypes;
+            if (generated && generated.questions.length > 0) {
+                finalQuestions = generated.questions;
+                strategies = generated.strategies;
+                underspecificationTypes = generated.underspecificationTypes;
+            }
+            else {
+                const fromDrafts = (query.questions ?? [])
+                    .map((d, i) => questionFromDraft(d, i))
+                    .filter((q) => q !== null);
+                if (fromDrafts.length === 0) {
+                    return error("Could not prepare structured questions. Ask the user directly in your response text instead.");
+                }
+                finalQuestions = fromDrafts;
+                strategies = fromDrafts.map(() => "surface_missing_detail");
+                underspecificationTypes = fromDrafts.map(() => null);
+            }
+            if (signal?.aborted) {
+                return error("The chat turn was cancelled before the questions could be shown.");
+            }
+            // ── 3. Persist (mode `chat`, linked to this conversation) ──────────
+            const timestamp = new Date().toISOString();
+            const batch = finalQuestions.map((payload, i) => ({
+                detection: {
+                    mode: "chat",
+                    sourceType: "conversation",
+                    sourceId: sessionId,
+                    timestamp,
+                },
+                actors: [{ userId: context.userId, role: "subject" }],
+                payload,
+                strategy: strategies[i] ?? "surface_missing_detail",
+                underspecificationType: underspecificationTypes[i] ?? null,
+                conversationId: sessionId,
+            }));
+            let persisted;
+            try {
+                persisted = await host.persist(batch);
+            }
+            catch (err) {
+                logger.error("Failed to persist chat questions", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return error("Could not deliver the questions to the user. Ask directly in your response text instead.");
+            }
+            // ── 4. Stream the cards to the frontend ────────────────────────────
+            emit({
+                type: "user_question",
+                questions: persisted.map((q) => ({ id: q.id })),
+            });
+            // ── 5. Block until answered / dismissed / timeout / abort ──────────
+            const heartbeat = setInterval(() => {
+                try {
+                    emit({ type: "status", message: "Waiting for your answer…" });
+                }
+                catch {
+                    /* stream may be closing; the wait resolves via timeout/abort */
+                }
+            }, WAIT_HEARTBEAT_MS);
+            let outcomes;
+            try {
+                outcomes = await host.awaitAnswers(persisted.map((q) => q.id), { timeoutMs: chatQuestionWaitTimeoutMs(), ...(signal ? { signal } : {}) });
+            }
+            finally {
+                clearInterval(heartbeat);
+            }
+            const byId = new Map(persisted.map((q) => [q.id, q]));
+            const results = outcomes.map((o) => {
+                const q = byId.get(o.questionId);
+                return {
+                    questionId: o.questionId,
+                    prompt: q?.payload.prompt ?? "",
+                    status: o.status,
+                    ...(o.answer
+                        ? {
+                            selectedOptions: o.answer.selectedOptions,
+                            ...(o.answer.freeText ? { freeText: o.answer.freeText } : {}),
+                        }
+                        : {}),
+                };
+            });
+            const answeredCount = results.filter((r) => r.status === "answered").length;
+            const timedOut = results.some((r) => r.status === "timeout");
+            return success({
+                answers: results,
+                summary: `${answeredCount} of ${results.length} question(s) answered`,
+                ...(timedOut
+                    ? {
+                        guidance: "The user has not answered the remaining question(s) yet. They stay visible in the conversation — acknowledge briefly, do NOT repeat the questions in text, and end your turn.",
+                    }
+                    : {}),
+            });
+        },
+    });
+    return [askUserQuestion];
+}
+/**
+ * Load a compact excerpt of the most recent conversation messages for the
+ * QuestionerAgent's grounding. Best-effort: returns "" on any failure or when
+ * no chat session reader is available.
+ */
+async function loadConversationExcerpt(deps, sessionId) {
+    if (!deps.chatSession)
+        return "";
+    try {
+        const messages = await deps.chatSession.getSessionMessages(sessionId, EXCERPT_FETCH_LIMIT);
+        if (!messages || messages.length === 0)
+            return "";
+        return messages
+            .slice(-EXCERPT_MESSAGE_COUNT)
+            .map((m) => {
+            const role = m.role === "assistant" ? "Assistant" : "User";
+            const text = (m.content ?? "").replace(/\s+/g, " ").trim();
+            return `${role}: ${text.slice(0, EXCERPT_MESSAGE_CHARS)}`;
+        })
+            .join("\n");
+    }
+    catch (err) {
+        logger.warn("Failed to load conversation excerpt", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return "";
+    }
+}

package/dist/questions/application/question.discovery.prompt.d.ts

@@ -0,0 +1,8 @@
+import type { DiscoveryQuestionInput } from "../../shared/schemas/discovery-question.schema.js";
+/** System prompt for the QuestionerAgent's `discovery` mode. */
+export declare const DISCOVERY_SYSTEM_PROMPT = "You help write user-facing follow-up questions after Index has reviewed potential connections for a human. Your job: surface the minimum set of structured decision questions the human must answer to make the next discovery turn sharper, or improve their outlook on the intent.\n\nYou may pick from five strategies. Choose contextually; mix when multiple questions genuinely complement.\n- refine_intent: ask the user to sharpen or pivot their original signal.\n- surface_missing_detail: ask for one concrete missing input (stage, location, timing, scope, \u2026).\n- open_adjacent_thread: offer a pivot suggested by recurring connection signals.\n- reflective_summary: mirror what the connection review revealed and ask the user to decide.\n- surface_emergent_knowledge: cite a fact you learned from the connection review and ask the user to decide in light of it.\n\nAsk a question only when ALL of these hold:\n1. Index cannot resolve the decision autonomously from the evidence shown.\n2. The answer would materially change which people surface next.\n3. The same fact is NOT already in chatContext.statedFacts, NOT already asked in chatContext.openQuestions, and NOT already shared in chatContext.surfacedFindings.\n\nStandalone prompt rule. Every generated `prompt` must be understandable outside the conversation where it was created. Naturally include the original query, discovery pattern, connection pattern, or concrete learned fact in the question text itself. Do not rely on `title`, UI labels, hidden metadata, or surrounding digest/chat text to explain what the question is about. For example, prefer \"For your AI crypto decentralized deep-tech search, which area is most critical right now?\" over \"Which area is most critical right now?\"\n\nReferential closure. The prompt must resolve entirely on its own, with no dangling references. The reader sees ONLY the question text \u2014 never the people you reviewed, the events on their calendar, or this conversation. Do not use demonstratives or definite anaphora that point at things the reader cannot see: \"these builders\", \"those founders\", \"these researchers\", \"these conversations\", \"this lunch\", \"the speaker\". If you reference a person, name them. If you reference a group, restate the concrete shared attribute inside the question itself (\"founders working on decentralized identity\"), never \"these founders\". Never imply a list, set, or prior exchange the reader is not currently looking at.\n- Bad: \"What kind of collaboration are you looking for with these builders?\"\n- Good: \"You're meeting people building agent infrastructure \u2014 what kind of collaboration are you looking for?\"\n\nNo process narration. Never describe Index's own activity or internal state. Forbidden: \"the previous negotiation\", \"the negotiation stalled\", \"opportunities found so far\", \"my search\", \"the counterparty\", \"candidates reviewed\", restating why a match did or did not happen, or quoting words a counterparty did or did not use. Ask about the user's goal or intent directly, never about the matching pipeline.\n- Bad: \"All opportunities found so far are related to 'Edge Esmeralda'. Would you like to broaden the search?\"\n- Good: \"Do you want to focus on people at Edge Esmeralda, or also connect beyond it?\"\n\nCardinality. Default one question. Add a second only when a DIFFERENT strategy genuinely complements the first (e.g. one surface_emergent_knowledge + one refine_intent). Add a third only when there are \u22653 substantive people reviewed and three distinct strategies each unblock a real decision. Two questions of the same strategy are acceptable only if their decision domains differ (different titles). Avoid stacking three pulls (info-from-user); balance with pushes (info-to-user via reflective_summary / surface_emergent_knowledge).\n\nOrdering. Questions whose answer unblocks the most connection reviews come first; then highest-impact; then ambiguity-clarifying. Reviews that needed more detail or ran out of time signal under-specification \u2014 prioritize.\n\nUser-facing language. Every title, prompt, option label, and option description is shown directly to the user. Never mention raw protocol mechanics or internal labels such as \"agent\", \"patient\", \"peer\", \"suggestedRoles\", \"role distribution\", \"counterparty\", \"negotiation\", \"turn_cap\", \"timeout\", or \"candidate\". Use natural language instead: people, matches, connections, mutual collaboration, someone who can help, or someone seeking help.\n\nOption construction. Each option must represent a meaningfully different outcome. Suffix the safest path with \" (Recommended)\" and list it first. The description states the CONSEQUENCE of choosing the option, not its definition. 2\u20134 options. Never add an \"Other\" option \u2014 clients provide a free-text fallback automatically. For surface_emergent_knowledge questions, anchor the prompt in the concrete cited fact (\"Multiple people flagged that\u2026\") and let the options represent decisions in light of that fact, not different versions of the fact.\n\nTitle rules. \u226412 chars. Noun of the decision domain. Discovery examples: \"Stage\", \"Timing\", \"Role\", \"Location\", \"Stack\", \"Budget\", \"Scope\", \"Format\".\n\nAnti-patterns \u2014 never do these.\n- Don't ask procedural confirmations (\"Should I look again?\").\n- Don't ask about hypothetical edge cases that didn't occur.\n- Don't ask about specific person identities; treat the provided person summary as the only allowed reference.\n- Don't repeat anything in chatContext.openQuestions.\n- Don't re-surface anything in chatContext.surfacedFindings.\n- Don't ask for facts in chatContext.statedFacts.\n\nOutput. Return at most 3 entries in the \"questions\" array. Each entry must include a \"strategy\" field (one of the five values). If nothing is worth asking, return \"questions\": [].";
+/**
+ * Pure builder: assembles the discovery-mode user message string from a
+ * structured input.
+ */
+export declare function buildDiscoveryQuestionPrompt(input: DiscoveryQuestionInput): string;

package/dist/questions/application/question.discovery.prompt.js

@@ -0,0 +1,181 @@
+/** System prompt for the QuestionerAgent's `discovery` mode. */
+export const DISCOVERY_SYSTEM_PROMPT = `You help write user-facing follow-up questions after Index has reviewed potential connections for a human. Your job: surface the minimum set of structured decision questions the human must answer to make the next discovery turn sharper, or improve their outlook on the intent.
+
+You may pick from five strategies. Choose contextually; mix when multiple questions genuinely complement.
+- refine_intent: ask the user to sharpen or pivot their original signal.
+- surface_missing_detail: ask for one concrete missing input (stage, location, timing, scope, …).
+- open_adjacent_thread: offer a pivot suggested by recurring connection signals.
+- reflective_summary: mirror what the connection review revealed and ask the user to decide.
+- surface_emergent_knowledge: cite a fact you learned from the connection review and ask the user to decide in light of it.
+
+Ask a question only when ALL of these hold:
+1. Index cannot resolve the decision autonomously from the evidence shown.
+2. The answer would materially change which people surface next.
+3. The same fact is NOT already in chatContext.statedFacts, NOT already asked in chatContext.openQuestions, and NOT already shared in chatContext.surfacedFindings.
+
+Standalone prompt rule. Every generated \`prompt\` must be understandable outside the conversation where it was created. Naturally include the original query, discovery pattern, connection pattern, or concrete learned fact in the question text itself. Do not rely on \`title\`, UI labels, hidden metadata, or surrounding digest/chat text to explain what the question is about. For example, prefer "For your AI crypto decentralized deep-tech search, which area is most critical right now?" over "Which area is most critical right now?"
+
+Referential closure. The prompt must resolve entirely on its own, with no dangling references. The reader sees ONLY the question text — never the people you reviewed, the events on their calendar, or this conversation. Do not use demonstratives or definite anaphora that point at things the reader cannot see: "these builders", "those founders", "these researchers", "these conversations", "this lunch", "the speaker". If you reference a person, name them. If you reference a group, restate the concrete shared attribute inside the question itself ("founders working on decentralized identity"), never "these founders". Never imply a list, set, or prior exchange the reader is not currently looking at.
+- Bad: "What kind of collaboration are you looking for with these builders?"
+- Good: "You're meeting people building agent infrastructure — what kind of collaboration are you looking for?"
+
+No process narration. Never describe Index's own activity or internal state. Forbidden: "the previous negotiation", "the negotiation stalled", "opportunities found so far", "my search", "the counterparty", "candidates reviewed", restating why a match did or did not happen, or quoting words a counterparty did or did not use. Ask about the user's goal or intent directly, never about the matching pipeline.
+- Bad: "All opportunities found so far are related to 'Edge Esmeralda'. Would you like to broaden the search?"
+- Good: "Do you want to focus on people at Edge Esmeralda, or also connect beyond it?"
+
+Cardinality. Default one question. Add a second only when a DIFFERENT strategy genuinely complements the first (e.g. one surface_emergent_knowledge + one refine_intent). Add a third only when there are ≥3 substantive people reviewed and three distinct strategies each unblock a real decision. Two questions of the same strategy are acceptable only if their decision domains differ (different titles). Avoid stacking three pulls (info-from-user); balance with pushes (info-to-user via reflective_summary / surface_emergent_knowledge).
+
+Ordering. Questions whose answer unblocks the most connection reviews come first; then highest-impact; then ambiguity-clarifying. Reviews that needed more detail or ran out of time signal under-specification — prioritize.
+
+User-facing language. Every title, prompt, option label, and option description is shown directly to the user. Never mention raw protocol mechanics or internal labels such as "agent", "patient", "peer", "suggestedRoles", "role distribution", "counterparty", "negotiation", "turn_cap", "timeout", or "candidate". Use natural language instead: people, matches, connections, mutual collaboration, someone who can help, or someone seeking help.
+
+Option construction. Each option must represent a meaningfully different outcome. Suffix the safest path with " (Recommended)" and list it first. The description states the CONSEQUENCE of choosing the option, not its definition. 2–4 options. Never add an "Other" option — clients provide a free-text fallback automatically. For surface_emergent_knowledge questions, anchor the prompt in the concrete cited fact ("Multiple people flagged that…") and let the options represent decisions in light of that fact, not different versions of the fact.
+
+Title rules. ≤12 chars. Noun of the decision domain. Discovery examples: "Stage", "Timing", "Role", "Location", "Stack", "Budget", "Scope", "Format".
+
+Anti-patterns — never do these.
+- Don't ask procedural confirmations ("Should I look again?").
+- Don't ask about hypothetical edge cases that didn't occur.
+- Don't ask about specific person identities; treat the provided person summary as the only allowed reference.
+- Don't repeat anything in chatContext.openQuestions.
+- Don't re-surface anything in chatContext.surfacedFindings.
+- Don't ask for facts in chatContext.statedFacts.
+
+Output. Return at most 3 entries in the "questions" array. Each entry must include a "strategy" field (one of the five values). If nothing is worth asking, return "questions": [].`;
+/**
+ * Pure builder: assembles the discovery-mode user message string from a
+ * structured input.
+ */
+export function buildDiscoveryQuestionPrompt(input) {
+    const profileSummary = input.userContext?.trim() || "(no profile data)";
+    const connectionReviewBlocks = renderConnectionReviewDigests(input.negotiationDigests);
+    const chatContextBlock = input.chatContext
+        ? renderDigest(input.chatContext)
+        : "(no chat context available)";
+    const engagementPattern = renderEngagementPattern(input.summary.roleDistribution);
+    return [
+        "## Seeker's query",
+        input.query,
+        "",
+        "## Seeker profile",
+        profileSummary,
+        "",
+        "## This discovery turn",
+        `- ${input.summary.totalCandidates} people reviewed`,
+        `- ${input.summary.opportunitiesFound} promising connections found`,
+        `- ${input.summary.noOpportunityCount} reviews did not find enough fit (${input.summary.timeoutCount} needed more detail or time)`,
+        `- Engagement pattern: ${engagementPattern}`,
+        "",
+        "## Connection review evidence (compact digests)",
+        connectionReviewBlocks,
+        "",
+        "## What the user has already said in this session",
+        chatContextBlock,
+        "",
+        "## Now",
+        input.now,
+        "",
+        "## Your task",
+        "Identify the minimum set of decision questions the seeker must answer to make",
+        "the next discovery turn sharper. Apply every rule from your system prompt",
+        "before outputting. Return an empty `questions` array if nothing is worth asking.",
+    ].join("\n");
+}
+/**
+ * Render the negotiation-digest collection into compact one-liners. Each digest
+ * is fixed-size (≤ ~400 chars after rendering), so the rendered block scales
+ * linearly with candidate count: 10 candidates ≈ 4 KB, well within budget.
+ */
+function renderConnectionReviewDigests(digests) {
+    if (digests.length === 0)
+        return "(no connection reviews)";
+    return digests
+        .map((d) => {
+        const relationshipSignal = d.suggestedRoles
+            ? [`  Relationship signal: ${renderRelationshipSignal(d.suggestedRoles)}`]
+            : [];
+        return [
+            `- Person: ${d.counterpartyHint}`,
+            `  Community context: ${d.indexContext}`,
+            `  Outcome: ${renderOutcome(d)}`,
+            ...relationshipSignal,
+            `  Take: ${d.keyTake}`,
+        ].join("\n");
+    })
+        .join("\n\n");
+}
+function renderEngagementPattern(dist) {
+    const parts = [];
+    if ((dist.peer ?? 0) > 0) {
+        parts.push(`${dist.peer} mutual collaboration${dist.peer === 1 ? "" : "s"}`);
+    }
+    if ((dist.agent ?? 0) > 0) {
+        parts.push(`${dist.agent} where the user could offer help or expertise`);
+    }
+    if ((dist.patient ?? 0) > 0) {
+        parts.push(`${dist.patient} where the user seemed to be seeking help or expertise`);
+    }
+    return parts.length > 0 ? parts.join(", ") : "(no engagement pattern available)";
+}
+function renderOutcome(digest) {
+    const outcome = digest.outcomeRole === "opportunity"
+        ? "promising connection"
+        : "not enough fit";
+    const reason = renderOutcomeReason(digest.outcomeReason);
+    return reason ? `${outcome} (${reason})` : outcome;
+}
+function renderOutcomeReason(reason) {
+    switch (reason) {
+        case "turn_cap":
+            return "needed more detail";
+        case "timeout":
+            return "ran out of time";
+        case "rejected":
+            return "not enough mutual interest";
+        case "stalled":
+            return "stalled";
+        case "screened_out":
+            return "didn't look like a strong enough fit to pursue";
+        case null:
+            return "";
+    }
+}
+function renderRelationshipSignal(roles) {
+    if (roles.ownUser === "peer" && roles.otherUser === "peer")
+        return "mutual collaboration";
+    if (roles.ownUser === "agent" && roles.otherUser === "patient") {
+        return "the user could offer help or expertise";
+    }
+    if (roles.ownUser === "patient" && roles.otherUser === "agent") {
+        return "the user seemed to be seeking help or expertise";
+    }
+    if (roles.ownUser === "agent")
+        return "the user could offer help or expertise";
+    if (roles.ownUser === "patient")
+        return "the user seemed to be seeking help or expertise";
+    return "collaboration fit";
+}
+function renderDigest(d) {
+    const lines = [];
+    if (d.statedFacts.length > 0) {
+        lines.push("Stated facts:");
+        for (const f of d.statedFacts)
+            lines.push(`  - ${f}`);
+    }
+    if (d.openQuestions.length > 0) {
+        lines.push("Open questions (assistant already asked):");
+        for (const q of d.openQuestions)
+            lines.push(`  - ${q}`);
+    }
+    if (d.rejectionReasons.length > 0) {
+        lines.push("User pushback / rejections:");
+        for (const r of d.rejectionReasons)
+            lines.push(`  - ${r}`);
+    }
+    if (d.surfacedFindings.length > 0) {
+        lines.push("Findings already surfaced to user:");
+        for (const f of d.surfacedFindings)
+            lines.push(`  - ${f}`);
+    }
+    return lines.length > 0 ? lines.join("\n") : "(digest is empty)";
+}