@nextclaw/ui 0.27.2 → 0.27.4

package/src/features/chat/features/conversation/components/__tests__/session-user-questions.test.tsx

@@ -0,0 +1,98 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { UiNcpSessionUserQuestionsView } from "@nextclaw/client-sdk";
+import { nextclawClient } from "@/shared/lib/api";
+import { SessionUserQuestionProvider, SessionUserQuestions, UserQuestionInlineQuestions, UserQuestionReplyReference } from "@/features/chat/features/conversation/components/session-user-questions";
+
+const questions: UiNcpSessionUserQuestionsView = {
+  sessionId: "session-1",
+  questions: [
+    { id: "q-1", messageId: "m-1", askedAt: "2026-09-28T00:00:00.000Z", title: "Which format?", options: ["PDF", "DOCX"], recommendedOption: "PDF", optionDescriptions: { PDF: "Keeps the layout fixed." }, status: "pending" },
+    { id: "q-2", messageId: "m-1", askedAt: "2026-09-28T00:00:00.000Z", title: "Which language?", status: "pending" },
+  ],
+};
+
+function renderQuestions() {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const onResolved = vi.fn(async () => undefined);
+  const view = render(
+    <QueryClientProvider client={queryClient}>
+      <SessionUserQuestionProvider sessionId="session-1" disabled={false} onResolved={onResolved}>
+        <UserQuestionInlineQuestions data={{ questions: questions.questions.map(({ id, title }) => ({ id, title })) }} />
+        <textarea aria-label="ordinary draft" defaultValue="keep this draft" />
+        <SessionUserQuestions />
+      </SessionUserQuestionProvider>
+    </QueryClientProvider>,
+  );
+  return { ...view, onResolved };
+}
+
+describe("SessionUserQuestions", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    sessionStorage.clear();
+  });
+
+  it("opens a new question, closes without losing it, reopens from its timeline label, and removes the settled composer entry", async () => {
+    let current = questions;
+    vi.spyOn(nextclawClient.sessions, "listUserQuestions").mockImplementation(async () => current);
+    const resolve = vi.spyOn(nextclawClient.sessions, "resolveUserQuestion").mockImplementation(async () => {
+      current = { ...questions, questions: questions.questions.map((question) => question.id === "q-1" ? { ...question, status: "answered" as const, answer: "PDF" } : question) };
+      return {
+        question: current.questions[0]!,
+        handle: { sessionId: "session-1", userMessageId: "answer-1", assistantMessageId: null, runId: "run-1", delivery: "steered" },
+      };
+    });
+    const { onResolved } = renderQuestions();
+    const autoPanel = await screen.findByRole("dialog", { name: "Which language?" });
+    fireEvent.click(within(autoPanel).getByRole("button", { name: "Which format?" }));
+    expect(screen.getByRole("dialog", { name: "Which format?" })).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: /关闭问题面板|Close question panel/ }));
+    expect(screen.queryByRole("dialog")).toBeNull();
+    const formatTag = screen.getByRole("button", { name: /Which format\?.*(待回答|Waiting)/ });
+    fireEvent.click(formatTag);
+    const panel = screen.getByRole("dialog", { name: "Which format?" });
+    expect(screen.queryByRole("button", { name: /待回答 2|2 to answer/ })).toBeNull();
+    expect(within(panel).getByRole("button", { name: /发送|Send/ }).hasAttribute("disabled")).toBe(true);
+    expect(within(panel).getByText(/推荐|Recommended/)).toBeTruthy();
+    fireEvent.click(within(panel).getByRole("button", { name: /PDF：(?:选项说明|Option details)/ }));
+    expect(await screen.findByRole("tooltip")).toHaveProperty("textContent", "Keeps the layout fixed.");
+    expect(resolve).not.toHaveBeenCalled();
+    fireEvent.click(within(panel).getByRole("button", { name: /^PDF\s+(推荐|Recommended)$/ }));
+    await waitFor(() => expect(resolve).toHaveBeenCalledWith("session-1", "q-1", { action: "answer", answer: "PDF" }));
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
+    expect(onResolved).toHaveBeenCalledTimes(1);
+    expect(screen.getByTitle("PDF").textContent).toMatch(/Which format\?.*(已回答|Answered)/);
+    expect(screen.getByRole("button", { name: /待回答 1|1 to answer/ })).toBeTruthy();
+    expect((screen.getByRole("textbox", { name: "ordinary draft" }) as HTMLTextAreaElement).value).toBe("keep this draft");
+  });
+
+  it("shows the custom answer as the last lettered option and submits it on Enter", async () => {
+    vi.spyOn(nextclawClient.sessions, "listUserQuestions").mockResolvedValue(questions);
+    const resolve = vi.spyOn(nextclawClient.sessions, "resolveUserQuestion").mockResolvedValue({
+      question: { ...questions.questions[0]!, status: "answered", answer: "ODT" },
+      handle: null,
+    });
+    renderQuestions();
+    const panel = await screen.findByRole("dialog", { name: "Which language?" });
+    fireEvent.click(within(panel).getByRole("button", { name: "Which format?" }));
+    const formatPanel = screen.getByRole("dialog", { name: "Which format?" });
+    const input = within(formatPanel).getByRole("textbox", { name: /你的回答|Your answer/ });
+    expect(input.getAttribute("placeholder")).toMatch(/自行|own/);
+    expect(input.parentElement?.textContent).toContain("C");
+    expect(resolve).not.toHaveBeenCalled();
+    fireEvent.change(input, { target: { value: "ODT" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    await waitFor(() => expect(resolve).toHaveBeenCalledWith("session-1", "q-1", { action: "answer", answer: "ODT" }));
+  });
+
+  it("renders the resolved message as a reference to the original question", () => {
+    render(<UserQuestionReplyReference data={{ questionId: "q-1", questionMessageId: "m-1", title: "Which format?", action: "answered", answer: "PDF" }} />);
+    const quote = screen.getByText("Which format?").closest("blockquote");
+    expect(quote?.getAttribute("data-chat-question-reference-id")).toBe("q-1");
+    expect(quote?.getAttribute("data-chat-question-message-id")).toBe("m-1");
+    expect(quote?.getAttribute("title")).toMatch(/Which format\?/);
+    expect(quote?.textContent).toBe("Which format?");
+  });
+});

package/src/features/chat/features/conversation/components/session-conversation-area.tsx

@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
+import type { NcpRunHandle } from "@nextclaw/ncp";
+import { SessionUserQuestionProvider, SessionUserQuestions } from "./session-user-questions";
 
 import { useAppPresenter } from "@/app/components/app-presenter-provider";
 import { ChatConversationContent } from "@/features/chat/components/conversation/chat-conversation-content";
@@ -419,7 +421,11 @@ export function SessionConversationArea(props: SessionConversationAreaProps) {
     !controller.isSending;
 
   return (
-    <>
+    <SessionUserQuestionProvider
+      sessionId={sessionKey}
+      disabled={isRuntimeBlocked}
+      onResolved={async (handle: NcpRunHandle) => { await agent.acceptRun(handle); }}
+    >
       <SessionConversationAlerts inputQuery={inputQuery} />
       <ChatConversationContent
         resourceWorkingDir={selectedSession?.workingDir ?? selectedSession?.projectRoot ?? null}
@@ -460,7 +466,12 @@ export function SessionConversationArea(props: SessionConversationAreaProps) {
           />
         }
       />
-      {showWelcome ? null : renderInput("default")}
-    </>
+      {showWelcome ? null : (
+        <>
+          <SessionUserQuestions />
+          {renderInput("default")}
+        </>
+      )}
+    </SessionUserQuestionProvider>
   );
 }

package/src/features/chat/features/conversation/components/session-conversation-input-top-slot.tsx

@@ -9,10 +9,11 @@ export function SessionConversationInputTopSlot({ inputSnapshot, controller }: {
   readonly controller: SessionConversationInputController;
 }) {
   const submission = inputSnapshot.pendingSubmission;
-  if (!submission && controller.queuedInputs.length === 0) return null;
+  const needsRecovery = submission && submission.status !== 'sending';
+  if (!needsRecovery && controller.queuedInputs.length === 0) return null;
   return <>
     {controller.queuedInputs.length > 0 && <SessionQueuedInputRows controller={controller} />}
-    {submission && <SubmissionStatus submission={submission} controller={controller}
+    {needsRecovery && <SubmissionStatus submission={submission} controller={controller}
       hasComposerContent={Boolean(inputSnapshot.text.trim() || inputSnapshot.selectedSkills.length || inputSnapshot.attachments.length)} />}
   </>;
 }
@@ -22,11 +23,9 @@ function SubmissionStatus({ submission, controller, hasComposerContent }: {
   readonly controller: SessionConversationInputController;
   readonly hasComposerContent: boolean;
 }) {
-  const statusText = submission.status === 'sending'
-    ? t('chatSubmissionSending')
-    : submission.status === 'rejected'
-      ? t('chatSubmissionRejected')
-      : t(submission.envelope.sessionId ? 'chatSendResultUnknown' : 'chatSendResultUnknownChild');
+  const statusText = submission.status === 'rejected'
+    ? t('chatSubmissionRejected')
+    : t(submission.envelope.sessionId ? 'chatSendResultUnknown' : 'chatSendResultUnknownChild');
   return <div className="rounded-lg border border-border bg-muted/50 px-3 py-2 text-sm" role="status">
     <p>{statusText}</p>
     <p className="mt-1 max-h-16 overflow-auto whitespace-pre-wrap text-muted-foreground">{submission.composer.text}</p>

package/src/features/chat/features/conversation/components/session-user-questions.tsx

@@ -0,0 +1,177 @@
+import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { ArrowRight, CircleHelp, CircleSlash, Loader2, MessageCircleQuestion, MessageSquareQuote, X } from "lucide-react";
+import type { NcpRunHandle } from "@nextclaw/client-sdk";
+import { nextclawClient } from "@/shared/lib/api";
+import { t } from "@/shared/lib/i18n";
+import { cn } from "@/shared/lib/utils";
+import type { ChatUserQuestionReply } from "@/features/chat/features/message/utils/chat-message.utils";
+import { ChatConversationTrack } from "@/features/chat/components/conversation/chat-conversation-track";
+import { useChatMessageLayoutStore } from "@/features/chat/stores/chat-message-layout.store";
+import { useSessionUserQuestions, type Question, type QuestionContext } from "@/features/chat/features/conversation/hooks/use-session-user-questions";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/shared/components/ui/tooltip";
+
+const context = createContext<QuestionContext | null>(null);
+
+export function SessionUserQuestionProvider({ children, sessionId, disabled, onResolved }: {
+  children: ReactNode;
+  sessionId: string | null;
+  disabled: boolean;
+  onResolved: (handle: NcpRunHandle) => Promise<void>;
+}) {
+  const value = useSessionUserQuestions({ sessionId, disabled, onResolved });
+  return <context.Provider value={value}>{children}</context.Provider>;
+}
+
+export function UserQuestionInlineQuestions({ data }: { data: unknown }) {
+  const state = useContext(context);
+  const entries = data && typeof data === "object" && !Array.isArray(data) ? (data as { questions?: unknown }).questions : null;
+  if (!Array.isArray(entries)) return null;
+  return (
+    <span className="inline-flex flex-wrap items-center gap-1.5 align-middle">
+      {entries.map((entry) => {
+        if (!entry || typeof entry !== "object" || typeof entry.id !== "string" || typeof entry.title !== "string") return null;
+        const question = state?.questions.find((item) => item.id === entry.id);
+        const status = question?.status ?? "pending";
+        const label = status === "answered" ? t("chatUserQuestionAnswered") : status === "dismissed" ? t("chatUserQuestionDismissed") : t("chatUserQuestionPending");
+        return status === "pending" ? (
+          <button key={entry.id} type="button" aria-expanded={state?.openId === entry.id} onClick={(event) => state?.openQuestion(entry.id, event.currentTarget)}
+            className="inline-flex max-w-full items-center gap-1.5 rounded-md border border-border bg-muted/60 px-2 py-1 text-xs leading-4 text-foreground transition-colors hover:border-[var(--interaction-selection-border)] hover:bg-[var(--interaction-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+            <MessageCircleQuestion aria-hidden="true" className="h-3.5 w-3.5 shrink-0" />
+            <span className="truncate">{entry.title}</span><span className="shrink-0 text-muted-foreground">{label}</span>
+          </button>
+        ) : (
+          <span key={entry.id} className="inline-flex max-w-full items-center gap-1.5 rounded-md bg-muted/40 px-2 py-1 text-xs leading-4 text-muted-foreground" title={question?.answer}>
+            <span className="truncate">{entry.title}</span><span>· {label}</span>
+          </span>
+        );
+      })}
+    </span>
+  );
+}
+
+export function UserQuestionReplyReference({ data }: { data: unknown }) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const reply = data as ChatUserQuestionReply;
+  if (typeof reply.questionId !== "string" || typeof reply.title !== "string") return null;
+  const dismissed = reply.action === "dismissed";
+  const label = dismissed ? t("chatUserQuestionDismissed") : t("chatUserQuestionReplyReference");
+  const Icon = dismissed ? CircleSlash : MessageSquareQuote;
+  return (
+    <blockquote data-chat-question-reference-id={reply.questionId}
+      data-chat-question-message-id={reply.questionMessageId ?? undefined}
+      aria-label={`${label}：${reply.title}`}
+      title={`${label}：${reply.title}`}
+      className="mb-2 flex max-w-full items-center gap-1.5 border-l-2 border-current/35 py-0.5 pl-2 text-xs leading-4 opacity-70">
+      <Icon aria-hidden="true" className="h-3.5 w-3.5 shrink-0" />
+      <span className="min-w-0 truncate">{reply.title}</span>
+    </blockquote>
+  );
+}
+
+function UserQuestionPanel({ question, pending, state }: { question: Question; pending: readonly Question[]; state: QuestionContext }) {
+  const [answer, setAnswer] = useState("");
+  const [selectedOption, setSelectedOption] = useState<string | null>(null);
+  const [activeHelp, setActiveHelp] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const submittingRef = useRef(false);
+  useEffect(() => { panelRef.current?.focus(); }, []);
+  useEffect(() => { if (!question.options?.length) inputRef.current?.focus(); }, [question.options]);
+  const resolve = async (action: "answer" | "dismiss", answerValue?: string) => {
+    if (!state.sessionId || submittingRef.current || (action === "answer" && !answerValue?.trim())) return;
+    submittingRef.current = true;
+    setSubmitting(true);
+    setError(null);
+    setSelectedOption(action === "answer" && question.options?.includes(answerValue ?? "") ? answerValue ?? null : null);
+    try {
+      const result = await nextclawClient.sessions.resolveUserQuestion(state.sessionId, question.id, {
+        action,
+        ...(action === "answer" ? { answer: answerValue?.trim() } : {}),
+      });
+      state.closeQuestion();
+      await state.refresh();
+      if (result.handle) await state.onResolved(result.handle);
+    } catch (cause) {
+      setSelectedOption(null);
+      setError(cause instanceof Error ? cause.message : t("chatUserQuestionFailed"));
+    } finally {
+      submittingRef.current = false;
+      setSubmitting(false);
+    }
+  };
+  return (
+    <div ref={panelRef} role="dialog" aria-label={question.title} tabIndex={-1}
+      onKeyDown={(event) => { if (event.key === "Escape") { event.stopPropagation(); state.closeQuestion(); } }}
+      className="max-h-[min(70vh,30rem)] overflow-y-auto rounded-2xl border border-border bg-card p-3 text-card-foreground shadow-card outline-none sm:p-4">
+      <div className="flex items-center justify-between gap-3 text-sm text-muted-foreground">
+        <div className="flex items-center gap-2"><CircleHelp aria-hidden="true" className="h-4 w-4" />{t("chatUserQuestionPanelHeading")}</div>
+        <button type="button" aria-label={t("chatUserQuestionClose")} onClick={state.closeQuestion} className="-mr-1 rounded-md p-1 hover:bg-[var(--interaction-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"><X className="h-4 w-4" /></button>
+      </div>
+      {pending.length > 1 ? <nav aria-label={t("chatUserQuestionsLabel")} className="mt-3 flex gap-1.5 overflow-x-auto pb-1">
+        {pending.map((item) => <button key={item.id} type="button" aria-current={item.id === question.id ? "true" : undefined}
+          onClick={() => state.openQuestion(item.id)}
+          className="shrink-0 rounded-md px-2 py-1 text-xs text-muted-foreground hover:bg-[var(--interaction-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring aria-[current=true]:bg-[var(--interaction-selection)] aria-[current=true]:text-foreground">{item.title}</button>)}
+      </nav> : null}
+      <h2 className="mt-3 text-base font-semibold leading-6">{question.title}</h2>
+      <TooltipProvider delayDuration={180}>
+        <div className="mt-2 space-y-0.5">
+          {question.options?.map((option, index) => {
+            const description = question.optionDescriptions?.[option];
+            return <div key={option} className={cn("group flex min-h-10 w-full items-center rounded-xl transition-colors hover:bg-[var(--interaction-hover)]", question.recommendedOption === option && "bg-[var(--interaction-selection)]")}>
+              <button type="button" aria-pressed={selectedOption === option} disabled={state.disabled || submitting} onClick={() => void resolve("answer", option)}
+                className="flex min-h-10 min-w-0 flex-1 items-center gap-2.5 rounded-xl px-2 py-1.5 text-left text-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50">
+                <span aria-hidden="true" className="flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-border bg-muted/50 text-xs text-muted-foreground">{index < 26 ? String.fromCharCode(65 + index) : index + 1}</span>
+                <span className="min-w-0 flex-1">{option}</span>
+                {question.recommendedOption === option ? <span className="shrink-0 text-xs text-muted-foreground">{t("chatUserQuestionRecommended")}</span> : null}
+                {submitting && selectedOption === option ? <Loader2 aria-label={t("chatUserQuestionSending")} className="h-4 w-4 animate-spin" /> : <ArrowRight aria-hidden="true" className={cn("h-4 w-4 shrink-0 text-muted-foreground transition-opacity", question.recommendedOption === option ? "opacity-70" : "opacity-0 group-hover:opacity-70 group-focus-within:opacity-70")} />}
+              </button>
+              {description ? <Tooltip open={activeHelp === option} onOpenChange={(open) => setActiveHelp(open ? option : null)}>
+                <TooltipTrigger asChild>
+                  <button type="button" aria-label={`${option}：${t("chatUserQuestionOptionHelp")}`} onClick={() => setActiveHelp(activeHelp === option ? null : option)}
+                    className="mr-2 flex h-7 w-7 shrink-0 items-center justify-center rounded-full text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+                    <CircleHelp aria-hidden="true" className="h-4 w-4" />
+                  </button>
+                </TooltipTrigger>
+                <TooltipContent side="top" align="end" className="max-w-64 whitespace-normal break-words text-xs">{description}</TooltipContent>
+              </Tooltip> : null}
+            </div>;
+          })}
+        </div>
+      </TooltipProvider>
+      <div className="mt-2 flex h-10 items-center gap-2.5 px-2">
+        <span aria-hidden="true" className="flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-border bg-muted/50 text-xs text-muted-foreground">{(question.options?.length ?? 0) < 26 ? String.fromCharCode(65 + (question.options?.length ?? 0)) : (question.options?.length ?? 0) + 1}</span>
+        <input ref={inputRef} aria-label={t("chatUserQuestionAnswerLabel")} value={answer} disabled={state.disabled || submitting} onChange={(event) => setAnswer(event.target.value)} onKeyDown={(event) => { if (event.key === "Enter") { event.preventDefault(); void resolve("answer", answer); } }} placeholder={t("chatUserQuestionAnswerPlaceholder")}
+          className="min-w-0 flex-1 border-0 bg-transparent p-0 text-sm text-foreground outline-none placeholder:text-muted-foreground disabled:opacity-50" />
+        <button type="button" disabled={state.disabled || submitting} onClick={() => void resolve("dismiss")} className="h-8 shrink-0 rounded-full border border-border px-3 text-xs hover:bg-[var(--interaction-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50">{t("chatUserQuestionDismiss")}</button>
+        <button type="button" disabled={state.disabled || submitting || !answer.trim()} onClick={() => void resolve("answer", answer)} className="h-8 shrink-0 rounded-full bg-primary px-3 text-xs font-medium text-primary-foreground hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:bg-muted disabled:text-muted-foreground">
+          {submitting && !selectedOption ? t("chatUserQuestionSending") : t("chatUserQuestionSend")}
+        </button>
+      </div>
+      {error ? <p role="alert" className="mt-2 text-xs text-destructive">{error}</p> : null}
+    </div>
+  );
+}
+
+export function SessionUserQuestions() {
+  const state = useContext(context);
+  const layout = useChatMessageLayoutStore((snapshot) => snapshot.layout);
+  if (!state?.sessionId) return null;
+  const pending = state.questions.filter((question) => question.status === "pending");
+  const openQuestion = pending.find((question) => question.id === state.openId);
+  if (!pending.length && !state.error) return null;
+  const content = (
+    <div className={cn("relative mx-auto w-full", layout !== "flat" && "max-w-[min(1120px,100%)] px-3 sm:px-4")} aria-label={t("chatUserQuestionsLabel")}>
+      {openQuestion ? <UserQuestionPanel key={openQuestion.id} question={openQuestion} pending={pending} state={state} /> : null}
+      {pending.length && !openQuestion ? <button type="button" aria-expanded={false} onClick={(event) => state.openQuestion(pending[pending.length - 1]!.id, event.currentTarget)}
+        className="inline-flex items-center gap-1.5 rounded-md px-1.5 py-1 text-xs text-muted-foreground hover:bg-[var(--interaction-hover)] hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+        <MessageCircleQuestion aria-hidden="true" className="h-3.5 w-3.5" />{t("chatUserQuestionsPendingCount").replace("{{count}}", String(pending.length))}
+      </button> : null}
+      {state.error ? <button type="button" onClick={() => void state.refresh()} className="ml-2 text-xs text-destructive underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">{t("chatUserQuestionFailed")} · {t("chatHistoryRetry")}</button> : null}
+    </div>
+  );
+  return layout === "flat"
+    ? <ChatConversationTrack width="composer">{content}</ChatConversationTrack>
+    : <div className="bg-background">{content}</div>;
+}

package/src/features/chat/features/conversation/hooks/use-session-user-questions.ts

@@ -0,0 +1,100 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { eventKeys, type NcpRunHandle, type UiNcpSessionUserQuestionsView } from "@nextclaw/client-sdk";
+import { NcpEventType } from "@nextclaw/ncp";
+import { nextclawClient } from "@/shared/lib/api";
+
+const QUESTION_QUERY_KEY = "session-user-questions";
+export type Question = UiNcpSessionUserQuestionsView["questions"][number];
+export type QuestionContext = {
+  questions: readonly Question[];
+  openId: string | null;
+  openQuestion: (id: string, trigger?: HTMLElement) => void;
+  closeQuestion: () => void;
+  sessionId: string | null;
+  disabled: boolean;
+  onResolved: (handle: NcpRunHandle) => Promise<void>;
+  refresh: () => Promise<void>;
+  error: boolean;
+};
+
+function readSeenIds(sessionId: string): Set<string> {
+  try {
+    return new Set(JSON.parse(sessionStorage.getItem(`nextclaw-question-seen:${sessionId}`) ?? "[]") as string[]);
+  } catch {
+    return new Set();
+  }
+}
+
+function markSeen(sessionId: string, ids: Set<string>) {
+  try {
+    sessionStorage.setItem(`nextclaw-question-seen:${sessionId}`, JSON.stringify([...ids]));
+  } catch { /* Storage may be disabled. The current mount still tracks seen IDs. */ }
+}
+
+export function useSessionUserQuestions({ sessionId, disabled, onResolved }: {
+  sessionId: string | null;
+  disabled: boolean;
+  onResolved: (handle: NcpRunHandle) => Promise<void>;
+}): QuestionContext {
+  const queryClient = useQueryClient();
+  const query = useQuery({
+    queryKey: [QUESTION_QUERY_KEY, sessionId],
+    queryFn: () => nextclawClient.sessions.listUserQuestions(sessionId as string),
+    enabled: Boolean(sessionId),
+    retry: false,
+    staleTime: 0,
+  });
+  const [manualOpen, setManualOpen] = useState<{ sessionId: string; id: string } | null>(null);
+  const [suppressed, setSuppressed] = useState<{ sessionId: string; ids: Set<string> } | null>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const questions = useMemo(() => query.data?.questions ?? [], [query.data]);
+  const pending = questions.filter((question) => question.status === "pending");
+  const seen = sessionId ? readSeenIds(sessionId) : new Set<string>();
+  if (suppressed?.sessionId === sessionId) for (const id of suppressed.ids) seen.add(id);
+  const autoOpenId = pending.findLast((question) => !seen.has(question.id))?.id ?? null;
+  const openId = manualOpen?.sessionId === sessionId && pending.some((question) => question.id === manualOpen.id)
+    ? manualOpen.id
+    : autoOpenId;
+  const refresh = async () => {
+    if (sessionId) await queryClient.invalidateQueries({ queryKey: [QUESTION_QUERY_KEY, sessionId], exact: true });
+  };
+  useEffect(() => {
+    if (!sessionId) return undefined;
+    const invalidate = () => void queryClient.invalidateQueries({ queryKey: [QUESTION_QUERY_KEY, sessionId], exact: true });
+    const unsubscribeEvent = nextclawClient.eventBus.on(eventKeys.ncpEvent, (event) => {
+      if (event.type !== NcpEventType.MessageSent || event.payload.sessionId !== sessionId) return;
+      const { message } = event.payload;
+      if (typeof message.metadata?.nextclaw_user_question_id === "string" ||
+          message.parts.some((part) => part.type === "extension" && part.extensionType === "nextclaw.user-question")) invalidate();
+    });
+    const unsubscribeQueue = nextclawClient.eventBus.on(eventKeys.sessionRunQueueUpdated, (event) => {
+      if (event.sessionKey === sessionId) invalidate();
+    });
+    return () => { unsubscribeEvent(); unsubscribeQueue(); };
+  }, [queryClient, sessionId]);
+  return {
+    questions,
+    openId,
+    openQuestion: (id, trigger) => {
+      if (!sessionId) return;
+      triggerRef.current = trigger ?? null;
+      setManualOpen({ sessionId, id });
+    },
+    closeQuestion: () => {
+      if (sessionId) {
+        const ids = new Set([...readSeenIds(sessionId), ...pending.map((question) => question.id)]);
+        markSeen(sessionId, ids);
+        setSuppressed({ sessionId, ids });
+      }
+      setManualOpen(null);
+      triggerRef.current?.focus();
+      triggerRef.current = null;
+    },
+    sessionId,
+    disabled,
+    onResolved,
+    refresh,
+    error: Boolean(query.error),
+  };
+}

package/src/features/chat/features/message/components/chat-message-list.container.tsx

@@ -16,6 +16,7 @@ import {
 import { usePresenter } from "@/features/chat/components/providers/chat-presenter.provider";
 import {
   adaptChatMessage,
+  readChatUserQuestionReply,
   type ChatMessageSource,
 } from "@/features/chat/features/message/utils/chat-message.utils";
 import { buildChatMessageProcessSummary } from "@/features/chat/features/message/utils/chat-message-process-summary.utils";
@@ -70,6 +71,7 @@ import { formatDateTime, t, type I18nLanguage } from "@/shared/lib/i18n";
 import { cn } from "@/shared/lib/utils";
 import type { SessionMessageToolPayloadState } from "@/features/chat/features/ncp/hooks/use-ncp-session-message-history";
 import { ChatMessageObservationEvent } from "@/features/chat/features/message/components/chat-message-observation-event";
+import { UserQuestionInlineQuestions, UserQuestionReplyReference } from "@/features/chat/features/conversation/components/session-user-questions";
 import {
   isObservationEventPartExtensionType,
   readObservationEventPartData,
@@ -166,6 +168,7 @@ class ChatMessageViewModelAdapter {
           processSummary,
           executionSummaryLabel: executionPresentation?.summaryLabel,
           moreActions,
+          userQuestionReply: readChatUserQuestionReply(message) ?? undefined,
         },
         parts: adaptNcpMessagePartsForChat(message.parts) as ChatMessageSource["parts"],
       };
@@ -407,6 +410,10 @@ export function ChatMessageListContainer({
   }, []);
   const renderCustomPart = useCallback(
     (part: Extract<ChatMessageViewModel["parts"][number], { type: "custom" }>) => {
+      if (part.customType === "nextclaw.user-question") {
+        return <UserQuestionInlineQuestions data={part.data} />;
+      }
+      if (part.customType === "nextclaw.user-question-reply") return <UserQuestionReplyReference data={part.data} />;
       if (isObservationEventPartExtensionType(part.customType)) {
         const event = readObservationEventPartData(part.data);
         return event ? <ChatMessageObservationEvent event={event} /> : undefined;

package/src/features/chat/features/message/utils/__tests__/chat-message.utils.test.ts

@@ -1,4 +1,6 @@
 import { ToolInvocationStatus, type UiMessage } from "@nextclaw/agent-chat";
+import type { NcpMessage } from "@nextclaw/ncp";
+import { readChatUserQuestionReply } from "@/features/chat/features/message/utils/chat-message.utils";
 import { adapt, toSource, type ChatMessageSource } from "./chat-message-test.utils";
 
 it("maps markdown, reasoning, and tool parts into UI view models", () => {
@@ -116,6 +118,49 @@ it("maps context compaction extensions into stable process parts", () => {
   }]);
 });
 
+it("renders a structured user question at its message position without repeating fallback text", () => {
+  const data = { questions: [{ id: "question-1", title: "Which format?", options: ["PDF", "DOCX"] }] };
+  const adapted = adapt([{
+    id: "assistant-question",
+    role: "assistant",
+    parts: [
+      { type: "text", text: "Which format? (PDF / DOCX)" },
+      { type: "extension", extensionType: "nextclaw.user-question", data },
+    ],
+  }]);
+  expect(adapted[0]?.parts).toEqual([{
+    type: "custom",
+    id: "question-1",
+    customType: "nextclaw.user-question",
+    data,
+  }]);
+});
+
+it("projects a delayed answer as a quoted question plus the actual answer", () => {
+  const message: NcpMessage = {
+    id: "answer-1",
+    sessionId: "session-1",
+    role: "user",
+    status: "final",
+    timestamp: "2026-09-28T00:00:00.000Z",
+    parts: [{ type: "text", text: "[Reply to an earlier question]\nQuestion: Which format?\nAnswer: PDF" }],
+    metadata: {
+      nextclaw_user_question_id: "q-1",
+      nextclaw_user_question_action: "answered",
+      nextclaw_user_question_title: "Which format?",
+      nextclaw_user_question_message_id: "asked-1",
+      nextclaw_user_question_answer: "PDF",
+    },
+  };
+  const reply = readChatUserQuestionReply(message);
+  expect(reply).toMatchObject({ questionId: "q-1", questionMessageId: "asked-1", title: "Which format?", answer: "PDF" });
+  const adapted = adapt([{ id: message.id, role: "user", meta: { userQuestionReply: reply! }, parts: [{ type: "text", text: message.parts[0]!.type === "text" ? message.parts[0]!.text : "" }] }]);
+  expect(adapted[0]?.parts).toEqual([
+    { type: "custom", id: "q-1", customType: "nextclaw.user-question-reply", data: reply },
+    { type: "markdown", text: "PDF" },
+  ]);
+});
+
 it("maps observation event extensions into visible custom parts", () => {
   const adapted = adapt([{
     id: "observation-event-message-1",

package/src/features/chat/features/message/utils/chat-message-part.utils.ts

@@ -250,6 +250,18 @@ function isToolInvocationPart(
 function buildExtensionPart(
   part: Extract<ChatMessagePartSource, { type: "extension" }>,
 ): Extract<ChatMessagePartViewModel, { type: "custom" }> | null {
+  if (part.extensionType === "nextclaw.user-question") {
+    const questions = typeof part.data === "object" && part.data !== null
+      ? (part.data as { questions?: unknown }).questions
+      : null;
+    if (!Array.isArray(questions) || !questions.length || typeof questions[0]?.id !== "string") return null;
+    return {
+      type: "custom",
+      id: questions[0].id,
+      customType: part.extensionType,
+      data: part.data,
+    };
+  }
   if (isObservationEventPartExtensionType(part.extensionType)) {
     const data = readObservationEventPartData(part.data);
     if (!data) return null;

package/src/features/chat/features/message/utils/chat-message.utils.ts

@@ -1,4 +1,5 @@
 import { adaptChatMessagePart } from "./chat-message-part.utils";
+import type { NcpMessage } from "@nextclaw/ncp";
 import type { ChatInlineTokenSource } from "@/features/chat/features/input/utils/chat-inline-token.utils";
 import type {
   ChatMessageMoreActionsViewModel,
@@ -26,10 +27,46 @@ export type ChatMessageSource = {
     processSummary?: ChatMessageProcessSummarySource;
     executionSummaryLabel?: string;
     moreActions?: ChatMessageMoreActionsViewModel;
+    userQuestionReply?: ChatUserQuestionReply;
   };
   parts: ChatMessagePartSource[];
 };
 
+export type ChatUserQuestionReply = {
+  questionId: string;
+  questionMessageId: string | null;
+  title: string;
+  action: "answered" | "dismissed";
+  answer: string | null;
+};
+
+export function readChatUserQuestionReply(message: NcpMessage): ChatUserQuestionReply | null {
+  if (message.role !== "user") return null;
+  const { metadata } = message;
+  const questionId = metadata?.nextclaw_user_question_id;
+  const action = metadata?.nextclaw_user_question_action;
+  if (typeof questionId !== "string" || (action !== "answered" && action !== "dismissed")) return null;
+  const text = message.parts.find((part) => part.type === "text");
+  const legacy = text?.type === "text" ? /^↳ ([^\n]+)\n([\s\S]*)$/.exec(text.text) : null;
+  const title = typeof metadata?.nextclaw_user_question_title === "string"
+    ? metadata.nextclaw_user_question_title
+    : legacy?.[1];
+  if (!title?.trim()) return null;
+  const answer = typeof metadata?.nextclaw_user_question_answer === "string"
+    ? metadata.nextclaw_user_question_answer
+    : legacy?.[2] ?? null;
+  if (action === "answered" && !answer?.trim()) return null;
+  return {
+    questionId,
+    questionMessageId: typeof metadata?.nextclaw_user_question_message_id === "string"
+      ? metadata.nextclaw_user_question_message_id
+      : null,
+    title,
+    action,
+    answer: action === "answered" ? answer : null,
+  };
+}
+
 function resolveMessageTimestamp(message: ChatMessageSource): string {
   const candidate = message.meta?.timestamp;
   if (candidate && Number.isFinite(Date.parse(candidate))) {
@@ -78,6 +115,23 @@ export function adaptChatMessage(
   message: ChatMessageSource,
   params: ChatMessageAdapterParams,
 ): ChatMessageViewModel {
+  const parts = message.parts
+    .map((part) => adaptChatMessagePart({
+      part,
+      inlineTokens: message.meta?.inlineTokens ?? [],
+      texts: params.texts,
+    }))
+    .filter((part) => part !== null);
+  const hasQuestionPart = parts.some(
+    (part) => part.type === "custom" && part.customType === "nextclaw.user-question",
+  );
+  const reply = message.meta?.userQuestionReply;
+  const displayParts: ChatMessageViewModel["parts"] = reply
+    ? [
+        { type: "custom", id: reply.questionId, customType: "nextclaw.user-question-reply", data: reply },
+        ...(reply.answer ? [{ type: "markdown" as const, text: reply.answer }] : []),
+      ]
+    : hasQuestionPart ? parts.filter((part) => part.type !== "markdown") : parts;
   return {
     id: message.id,
     role: resolveUiRole(message.role),
@@ -87,15 +141,7 @@ export function adaptChatMessage(
     processSummary: message.meta?.processSummary,
     executionSummaryLabel: message.meta?.executionSummaryLabel,
     moreActions: message.meta?.moreActions,
-    parts: message.parts
-      .map((part) =>
-        adaptChatMessagePart({
-          part,
-          inlineTokens: message.meta?.inlineTokens ?? [],
-          texts: params.texts,
-        }),
-      )
-      .filter((part) => part !== null),
+    parts: displayParts,
   };
 }