@indexnetwork/protocol 21.1.0-rc.492.1 → 22.0.0-rc.494.1

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

@@ -1,297 +0,0 @@
-/**
- * questions/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).
- */
-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/question.persistence.port.d.ts

@@ -1,84 +0,0 @@
-/**
- * questions/question.persistence.port — question persistence contracts.
- *
- * Protocol-level persistence contract for structured questions generated by
- * QuestionerAgent. Implementations live in the backend and are injected into
- * ProtocolDeps.
- */
-import type { Question, QuestionMode, QuestionPurpose, QuestionStrategy, QuestionDetection, QuestionActor, QuestionAnswer, UnderspecificationType } from "./question.schema.js";
-/** Shape accepted by `persist()` — everything needed to insert a question row. */
-export interface PersistableQuestion {
-    detection: QuestionDetection;
-    actors: QuestionActor[];
-    payload: Question;
-    strategy: QuestionStrategy;
-    /** Internal QUD repair category; null when the question repairs no underspecification. */
-    underspecificationType?: UnderspecificationType | null;
-    /** Conversation ID — set when the question originates from a chat session. */
-    conversationId?: string;
-}
-/** Shape returned by `findPending()` — a persisted question with its DB id and status. */
-export interface PersistedQuestion {
-    id: string;
-    detection: QuestionDetection;
-    actors: QuestionActor[];
-    payload: Question;
-    status: "pending" | "answered" | "dismissed";
-    answer: QuestionAnswer | null;
-    createdAt: string;
-}
-/** Optional filters for `findPending()`. */
-export interface QuestionFilters {
-    mode?: QuestionMode;
-    purpose?: QuestionPurpose;
-    sourceType?: string;
-    sourceId?: string;
-    /** Optional selected-intent scope. When `scopeType === 'intent'`, `scopeId` is the selected intent id. */
-    scopeType?: 'intent';
-    scopeId?: string;
-}
-/**
- * Resolution outcome for a single awaited chat question.
- * `timeout` means the wait budget elapsed (or the run was aborted) before the
- * user responded — the question stays `pending` in the database.
- */
-export interface ChatQuestionAnswerOutcome {
-    questionId: string;
-    status: "answered" | "dismissed" | "timeout";
-    answer?: QuestionAnswer;
-}
-/**
- * Host bridge for the orchestrator's blocking `ask_user_question` tool.
- * `persist` synchronously inserts chat-mode question rows; `awaitAnswers`
- * blocks until every question resolves (answer/dismiss via the questions
- * REST endpoints) or the wait times out / the run is aborted.
- *
- * Implementations live in the backend (in-memory per-question wait bus,
- * single-instance semantics like the chat steer/queue interrupt emitter).
- */
-export interface ChatQuestionsHost {
-    persist(batch: PersistableQuestion[]): Promise<PersistedQuestion[]>;
-    awaitAnswers(questionIds: string[], opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<ChatQuestionAnswerOutcome[]>;
-}
-/**
- * Narrow persistence port for ambient question delivery adapters.
- * Inject this instead of QuestionerDatabase when only persistence is needed.
- */
-export interface QuestionerDatabase {
-    /** Persist a batch of generated questions (up to 3 per generation).
-     *  @returns The IDs of the inserted rows. */
-    persist(questions: PersistableQuestion[]): Promise<string[]>;
-    /** Find pending questions for a user, optionally filtered by mode/source. */
-    findPending(userId: string, filters?: QuestionFilters): Promise<PersistedQuestion[]>;
-    /** Record an answer for a question. Sets status to "answered".
-     *  Only succeeds if the user is an actor on a pending question.
-     *  @returns `true` if updated, `false` if not found, not pending, or unauthorized. */
-    answer(questionId: string, userId: string, answer: QuestionAnswer): Promise<boolean>;
-    /** Dismiss a question. Sets status to "dismissed".
-     *  Only succeeds if the user is an actor on a pending question.
-     *  @returns `true` if updated, `false` if not found, not pending, or unauthorized. */
-    dismiss(questionId: string, userId: string): Promise<boolean>;
-}

package/dist/questions/question.persistence.port.js

@@ -1 +0,0 @@
-export {};

package/dist/questions/question.presets.d.ts

@@ -1,21 +0,0 @@
-/**
- * questions/question.presets — mode presets for QuestionerAgent.
- *
- * Each preset provides a system prompt and a buildPrompt function that assembles
- * the user message from a typed context object.
- */
-import type { QuestionMode, QuestionPurpose } from "./question.schema.js";
-export interface QuestionerPreset {
-    /** The LLM system prompt for this mode. */
-    systemPrompt: string;
-    /** Builds the user-message string from the mode-specific context. */
-    buildPrompt: (context: unknown) => string;
-}
-/**
- * Retrieve the preset for the given mode.
- * @param mode - The question mode to look up.
- * @param purpose - Optional purpose discriminant (for intent-recovery variant).
- * @returns The matching preset with systemPrompt and buildPrompt.
- * @throws Error if the mode's preset is not yet implemented.
- */
-export declare function getPreset(mode: QuestionMode, purpose?: QuestionPurpose): QuestionerPreset;