@indexnetwork/protocol 6.12.1-rc.404.1 → 6.14.0-rc.406.1

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

@@ -0,0 +1,190 @@
+/**
+ * questions/application/question.tools — foreground adapter: MCP question tools.
+ *
+ * Creates MCP tool definitions for the questions domain. Exposes
+ * `read_pending_questions` and `answer_pending_question` for retrieving and
+ * settling the caller's pending questions generated by QuestionerAgent
+ * (enrichment, intent, negotiation, discovery modes).
+ *
+ * Foreground adapter: these tools respond to authenticated user actions
+ * (read, answer, dismiss). Ambient delivery adapters are handled separately
+ * via the QuestionerQueue.
+ *
+ * IND-547: canonical home — previously questioner/questioner.tools.ts.
+ * Legacy path is a thin compatibility shim pointing here.
+ */
+import { z } from "zod";
+import { error, success } from "../../shared/agent/tool.helpers.js";
+import { focusedIntentId, focusedNetworkId, focusedNetworkLabel } from "../../shared/agent/tool.scope.js";
+/**
+ * Detection modes whose questions derive solely from the caller's own data
+ * (profile gaps, own intents, own discovery sessions). Negotiation-mode
+ * questions are excluded for network-scoped agents: their prompts are seeded
+ * from opportunity metadata that can reference out-of-scope networks and
+ * other users' content (same leak class as the getOpportunitiesForUser fix).
+ */
+const SELF_OWNED_MODES = ["enrichment", "intent", "discovery"];
+function isVisibleInScopedNetwork(question, userId, networkId) {
+    return question.actors?.some((actor) => actor.userId === userId && actor.networkId === networkId) === true;
+}
+function stripInternalQuestionFields(question) {
+    const { actors: _actors, purpose: _purpose, ...publicQuestion } = question;
+    return publicQuestion;
+}
+/**
+ * Creates MCP tool definitions for the questioner domain.
+ *
+ * Network-scoped agent keys (context.scopeType/scopeId set via applyNetworkScopeToContext)
+ * are clamped to self-owned modes; the result then carries a `scopeRestriction`
+ * block mirroring the network-tools convention.
+ *
+ * @param defineTool - Tool factory provided by the composition root.
+ * @param deps       - Shared tool dependencies; `findPendingQuestions` and
+ *                     `answerPendingQuestion` are optional and the tools fail
+ *                     gracefully when absent.
+ */
+export function createQuestionerTools(defineTool, deps) {
+    const readPendingQuestions = defineTool({
+        name: "read_pending_questions",
+        description: "Returns pending questions generated for the authenticated user across all modes " +
+            "(profile, intent, negotiation, discovery). These are questions generated by the " +
+            "system to help surface missing signals, refine intents, or capture engagement context.\n\n" +
+            "**Returns:** List of pending questions, each with `id`, `title`, `prompt`, `options`, " +
+            "`multiSelect`, `mode`, `sourceType`, `sourceId`, `createdAt`, and optional `expiresAt`. " +
+            "Network-scoped agents receive only profile/intent/discovery questions for the scoped network plus a " +
+            "`scopeRestriction` note.\n\n" +
+            "**Use:** Call with no arguments to get all pending questions, or pass `limit` to cap the " +
+            "count. For the daily brief the script calls with a small `limit` and renders the first " +
+            "question that has not been delivered yet.",
+        querySchema: z.object({
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .optional()
+                .describe("Maximum number of questions to return (1-10, default 10)."),
+        }),
+        handler: async ({ context, query }) => {
+            if (!deps.findPendingQuestions) {
+                return error("Question lookup is not available.");
+            }
+            const limit = query.limit ?? 10;
+            const scopedNetworkId = focusedNetworkId(context);
+            const scopedIntentId = focusedIntentId(context);
+            const isNetworkScoped = Boolean(scopedNetworkId);
+            const isIntentScoped = Boolean(scopedIntentId);
+            try {
+                const fetched = await deps.findPendingQuestions(context.userId, {
+                    ...(isNetworkScoped ? { modes: SELF_OWNED_MODES, networkId: scopedNetworkId } : {}),
+                    ...(isIntentScoped ? { scopeType: 'intent', scopeId: scopedIntentId } : {}),
+                    limit,
+                });
+                const visible = isNetworkScoped
+                    ? fetched.filter((q) => SELF_OWNED_MODES.includes(q.mode) &&
+                        isVisibleInScopedNetwork(q, context.userId, scopedNetworkId))
+                    : fetched;
+                const limited = visible.slice(0, limit).map(stripInternalQuestionFields);
+                if (isIntentScoped) {
+                    return success({
+                        questions: limited,
+                        scopeRestriction: {
+                            isScoped: true,
+                            scopedToIntent: scopedIntentId,
+                            message: "Results are restricted to the selected intent, including direct intent questions and negotiation questions from matching opportunities.",
+                        },
+                    });
+                }
+                if (isNetworkScoped) {
+                    return success({
+                        questions: limited,
+                        scopeRestriction: {
+                            isScoped: true,
+                            scopedToIndex: focusedNetworkLabel(context),
+                            message: `Results are restricted to "${context.indexName ?? "this network"}" and ` +
+                                `exclude negotiation questions because this agent is scoped to that index.`,
+                        },
+                    });
+                }
+                return success({ questions: limited });
+            }
+            catch (err) {
+                deps.reportToolError?.(err, {
+                    operation: "read-pending-questions",
+                    toolName: "read_pending_questions",
+                    userId: context.userId,
+                });
+                return error("Failed to read pending questions.");
+            }
+        },
+    });
+    const answerPendingQuestion = defineTool({
+        name: "answer_pending_question",
+        description: "Records the client's explicit answer to one of their pending questions (from " +
+            "read_pending_questions) through the standard answer pipeline — the same one the " +
+            "question cards in the app use. Downstream effects (signal refinement, negotiation " +
+            "context, profile enrichment) fire exactly as if the client answered the card.\n\n" +
+            "**Use ONLY with an answer the client explicitly gave in this conversation.** Never " +
+            "infer, summarize, or invent an answer on their behalf. Pass the client's chosen " +
+            "option labels in `selectedOptions` and/or their own words in `freeText`.\n\n" +
+            "**Returns:** `answered: true` on success. If the question was already answered, " +
+            "dismissed, or expired, the tool reports that — tell the client instead of retrying.",
+        querySchema: z.object({
+            questionId: z.string().min(1).describe("Id of the pending question being answered (from read_pending_questions)."),
+            selectedOptions: z
+                .array(z.string().min(1))
+                .max(10)
+                .optional()
+                .describe("Option labels the client explicitly chose, when the question has options."),
+            freeText: z
+                .string()
+                .max(2000)
+                .optional()
+                .describe("The client's answer in their own words, for free-form answers or an 'other' option."),
+        }),
+        handler: async ({ context, query }) => {
+            if (!deps.answerPendingQuestion || !deps.findPendingQuestions) {
+                return error("Question answering is not available.");
+            }
+            if (focusedNetworkId(context)) {
+                return error("Answering questions is not available for network-scoped agents.");
+            }
+            const selectedOptions = (query.selectedOptions ?? []).map((option) => option.trim()).filter(Boolean);
+            const freeText = query.freeText?.trim();
+            if (selectedOptions.length === 0 && !freeText) {
+                return error("No answer provided. Pass the client's explicit answer via selectedOptions and/or freeText — never answer on their behalf.");
+            }
+            const scopedIntentId = focusedIntentId(context);
+            try {
+                const pending = await deps.findPendingQuestions(context.userId, {
+                    ...(scopedIntentId ? { scopeType: 'intent', scopeId: scopedIntentId } : {}),
+                });
+                const target = pending.find((q) => q.id === query.questionId);
+                if (!target) {
+                    return error("Question not found among the client's pending questions — it may already be answered or dismissed. Re-check with read_pending_questions.");
+                }
+                const answered = await deps.answerPendingQuestion(context.userId, query.questionId, {
+                    selectedOptions,
+                    ...(freeText ? { freeText } : {}),
+                });
+                if (!answered) {
+                    return error("The question was already answered or dismissed — nothing was recorded.");
+                }
+                return success({
+                    answered: true,
+                    question: { id: target.id, title: target.title, prompt: target.prompt },
+                    recordedAnswer: { selectedOptions, ...(freeText ? { freeText } : {}) },
+                });
+            }
+            catch (err) {
+                deps.reportToolError?.(err, {
+                    operation: "answer-pending-question",
+                    toolName: "answer_pending_question",
+                    userId: context.userId,
+                });
+                return error("Failed to record the answer.");
+            }
+        },
+    });
+    return [readPendingQuestions, answerPendingQuestion];
+}

package/dist/questions/domain/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * questions/domain — pure question value types and schemas.
+ *
+ * Contains Zod schemas and TypeScript types that define the questions
+ * capability's domain language.  No LLM calls, no agents, no cross-capability
+ * imports beyond zod.
+ *
+ * ## What lives here
+ *
+ * - **question.schema** — Question, QuestionWithStrategy, QuestionDetection,
+ *   QuestionMode, QuestionPurpose, NegotiationQuestionCandidate,
+ *   NegotiationQuestionProvenance, pool/push/recovery sub-schemas, and all
+ *   derived TypeScript types.
+ *
+ * ## What does NOT live here
+ *
+ * - QuestionerInput/QuestionerContext: they reference capability facades
+ *   (negotiation question-safety) and belong in questions/application.
+ * - QuestionerAgent and tool factories: application layer.
+ * - Persistence/generator ports: questions/ports.
+ *
+ * IND-547: canonical home for question domain types.
+ * Legacy path (shared/schemas/question.schema.ts) is a thin compatibility shim.
+ */
+export * from "./question.schema.js";

package/dist/questions/domain/index.js

@@ -0,0 +1,25 @@
+/**
+ * questions/domain — pure question value types and schemas.
+ *
+ * Contains Zod schemas and TypeScript types that define the questions
+ * capability's domain language.  No LLM calls, no agents, no cross-capability
+ * imports beyond zod.
+ *
+ * ## What lives here
+ *
+ * - **question.schema** — Question, QuestionWithStrategy, QuestionDetection,
+ *   QuestionMode, QuestionPurpose, NegotiationQuestionCandidate,
+ *   NegotiationQuestionProvenance, pool/push/recovery sub-schemas, and all
+ *   derived TypeScript types.
+ *
+ * ## What does NOT live here
+ *
+ * - QuestionerInput/QuestionerContext: they reference capability facades
+ *   (negotiation question-safety) and belong in questions/application.
+ * - QuestionerAgent and tool factories: application layer.
+ * - Persistence/generator ports: questions/ports.
+ *
+ * IND-547: canonical home for question domain types.
+ * Legacy path (shared/schemas/question.schema.ts) is a thin compatibility shim.
+ */
+export * from "./question.schema.js";