@nextclaw/ui 0.27.3 → 0.27.5-beta.0

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-timeline.utils.test.ts

@@ -20,6 +20,22 @@ const visibleMessage = {
 } satisfies NcpMessage;
 
 describe("chat message timeline visibility", () => {
+  it("places an async question at its tool call between assistant text parts", () => {
+    const source = { ...visibleMessage, parts: [
+      { type: "text" as const, text: "先说明。" },
+      { type: "tool-invocation" as const, toolCallId: "call-1", toolName: "request_user_input_async", state: "result" as const,
+        args: "{}", result: { accepted: true, questionIds: ["q-1"] } },
+      { type: "text" as const, text: "稍后继续。" },
+    ] } satisfies NcpMessage;
+    const question = { ...visibleMessage, id: "assistant-question-1", parts: [
+      { type: "text" as const, text: "城市？ (北京 / 上海)" },
+      { type: "extension" as const, extensionType: "nextclaw.user-question", data: { questions: [{ id: "q-1", title: "城市？", options: ["北京", "上海"] }] } },
+    ] } satisfies NcpMessage;
+    const projected = projectVisibleChatMessages([source, question]);
+    expect(projected).toHaveLength(1);
+    expect(projected[0]?.parts.map((part) => part.type)).toEqual(["text", "extension", "text"]);
+    expect(projected[0]?.parts[1]).toMatchObject({ data: { questions: [{ id: "q-1" }] } });
+  });
   it("places context compaction between surrounding visible messages", () => {
     const afterMessage = {
       ...visibleMessage,

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,66 @@ it("maps context compaction extensions into stable process parts", () => {
   }]);
 });
 
+it("keeps assistant prose on both sides of an unanchored question fallback", () => {
+  const data = { questions: [{ id: "question-1", title: "Which format?", options: ["PDF", "DOCX"] }] };
+  const adapted = adapt([{
+    id: "assistant-question-older",
+    role: "assistant",
+    parts: [
+      { type: "text", text: "Before." },
+      { type: "text", text: "Which format? (PDF / DOCX)" },
+      { type: "extension", extensionType: "nextclaw.user-question", data },
+      { type: "text", text: "After." },
+    ],
+  }]);
+  expect(adapted[0]?.parts.map((part) => part.type)).toEqual(["markdown", "custom", "markdown"]);
+  expect(adapted[0]?.parts[0]).toMatchObject({ text: "Before." });
+  expect(adapted[0]?.parts[2]).toMatchObject({ text: "After." });
+});
+
+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-timeline.utils.ts

@@ -13,10 +13,10 @@ import {
   readObservationEventPartData,
   type ObservationEventPartData,
 } from "@/features/chat/features/message/utils/chat-message-observation-event.utils";
+import { placeUserQuestionsInAssistantBody } from "@/features/chat/features/message/utils/chat-user-question-timeline.utils";
 
 const INHERITED_FROM_SESSION_METADATA_KEY = "inherited_from_session_id";
-export const CONTEXT_COMPACTION_PART_EXTENSION_TYPE =
-  "nextclaw.context-compaction";
+export const CONTEXT_COMPACTION_PART_EXTENSION_TYPE = "nextclaw.context-compaction";
 
 export type ContextCompactionPartData = {
   id: string;
@@ -280,7 +280,7 @@ function projectVisibleChatMessageState(
       status: "pending",
     };
   }
-  return { messages, inlineCompactionMessageIds, observationEvents };
+  return { ...placeUserQuestionsInAssistantBody(messages, observationEvents), inlineCompactionMessageIds };
 }
 
 export function projectVisibleChatMessages(

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,30 @@ 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 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 }] : []),
+      ]
+    : parts.filter((part, index) => {
+        const next = parts[index + 1];
+        if (part.type !== "markdown" || next?.type !== "custom" || next.customType !== "nextclaw.user-question") return true;
+        const entries = next.data && typeof next.data === "object" && "questions" in next.data ? next.data.questions : null;
+        if (!Array.isArray(entries)) return true;
+        const fallback = entries.map((entry) => {
+          if (!entry || typeof entry.title !== "string") return "";
+          return `${entry.title}${Array.isArray(entry.options) && entry.options.length ? ` (${entry.options.join(" / ")})` : ""}`;
+        }).join("\n");
+        return part.text !== fallback;
+      });
   return {
     id: message.id,
     role: resolveUiRole(message.role),
@@ -87,15 +148,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,
   };
 }
 

package/src/features/chat/features/message/utils/chat-user-question-timeline.utils.ts

@@ -0,0 +1,42 @@
+import type { NcpMessage } from "@nextclaw/ncp";
+
+function questionIdsFromToolPart(part: NcpMessage["parts"][number]): string[] {
+  if (part.type !== "tool-invocation" || part.toolName !== "request_user_input_async" ||
+    !part.result || typeof part.result !== "object" || Array.isArray(part.result)) return [];
+  const { accepted, questionIds } = part.result as { accepted?: unknown; questionIds?: unknown };
+  return accepted === true && Array.isArray(questionIds) && questionIds.every((id) => typeof id === "string")
+    ? questionIds : [];
+}
+
+function questionEntries(part: NcpMessage["parts"][number]): Array<{ id: string }> {
+  if (part.type !== "extension" || part.extensionType !== "nextclaw.user-question") return [];
+  const entries = part.data && typeof part.data === "object" && "questions" in part.data ? part.data.questions : null;
+  return Array.isArray(entries) ? entries.filter((entry): entry is { id: string } => Boolean(entry && typeof entry.id === "string")) : [];
+}
+
+export function placeUserQuestionsInAssistantBody<T extends { boundaryIndex: number }>(
+  messages: NcpMessage[], observationEvents: T[],
+): { messages: NcpMessage[]; observationEvents: T[] } {
+  const entriesById = new Map(messages.flatMap((message) => message.parts.flatMap((part) => questionEntries(part).map((entry) => [entry.id, entry] as const))));
+  const anchoredIds = new Set(messages.flatMap((message) => message.parts.flatMap((part) =>
+    questionIdsFromToolPart(part).filter((id) => entriesById.has(id)))));
+  if (!anchoredIds.size) return { messages, observationEvents };
+  const removedIndices: number[] = [];
+  const projected = messages.flatMap((message, index) => {
+    const questionPart = message.parts.find((part) => questionEntries(part).length);
+    if (questionPart && message.id.startsWith("assistant-question-")) {
+      const remaining = questionEntries(questionPart).filter((entry) => !anchoredIds.has(entry.id));
+      if (!remaining.length) { removedIndices.push(index); return []; }
+      return [{ ...message, parts: [{ type: "extension" as const, extensionType: "nextclaw.user-question", data: { questions: remaining } }] }];
+    }
+    const parts = message.parts.flatMap((part): NcpMessage["parts"] => {
+      const questions = questionIdsFromToolPart(part).flatMap((id) => entriesById.get(id) ?? []);
+      return questions.length
+        ? [{ type: "extension", extensionType: "nextclaw.user-question", data: { questions } }]
+        : [part];
+    });
+    return [{ ...message, parts }];
+  });
+  return { messages: projected, observationEvents: observationEvents.map((entry) => ({ ...entry,
+    boundaryIndex: entry.boundaryIndex - removedIndices.filter((index) => index < entry.boundaryIndex).length })) };
+}

package/src/shared/lib/i18n/locales/en-US/chat.json

@@ -500,6 +500,22 @@
   "chatContextInheritanceMessages": "Inherited messages",
   "chatSending": "Sending...",
   "chatQueueSend": "Queue",
+  "chatUserQuestionsLabel": "Questions from your agent",
+  "chatUserQuestionPanelHeading": "Question",
+  "chatUserQuestionsPendingCount": "{{count}} to answer",
+  "chatUserQuestionClose": "Close question panel",
+  "chatUserQuestionPending": "Waiting for you",
+  "chatUserQuestionAnswered": "Answered",
+  "chatUserQuestionDismissed": "Skipped",
+  "chatUserQuestionAnswerLabel": "Your answer",
+  "chatUserQuestionAnswerPlaceholder": "Or write your own reply",
+  "chatUserQuestionRecommended": "Recommended",
+  "chatUserQuestionOptionHelp": "Option details",
+  "chatUserQuestionReplyReference": "Referenced question",
+  "chatUserQuestionDismiss": "Skip",
+  "chatUserQuestionSend": "Send",
+  "chatUserQuestionSending": "Sending…",
+  "chatUserQuestionFailed": "Could not update this question",
   "chatQueuedBannerAttachmentFallback": "Attachment message",
   "chatQueuedSubmitting": "Adding to queue…",
   "chatQueuedEdit": "Edit queued input",

package/src/shared/lib/i18n/locales/zh-CN/chat.json

@@ -500,6 +500,22 @@
   "chatContextInheritanceMessages": "继承消息数",
   "chatSending": "发送中...",
   "chatQueueSend": "排队发送",
+  "chatUserQuestionsLabel": "智能体提出的问题",
+  "chatUserQuestionPanelHeading": "问题",
+  "chatUserQuestionsPendingCount": "待回答 {{count}}",
+  "chatUserQuestionClose": "关闭问题面板",
+  "chatUserQuestionPending": "待回答",
+  "chatUserQuestionAnswered": "已回答",
+  "chatUserQuestionDismissed": "已跳过",
+  "chatUserQuestionAnswerLabel": "你的回答",
+  "chatUserQuestionAnswerPlaceholder": "或自行填写回复",
+  "chatUserQuestionRecommended": "推荐",
+  "chatUserQuestionOptionHelp": "选项说明",
+  "chatUserQuestionReplyReference": "引用问题",
+  "chatUserQuestionDismiss": "跳过",
+  "chatUserQuestionSend": "发送",
+  "chatUserQuestionSending": "发送中…",
+  "chatUserQuestionFailed": "问题更新失败",
   "chatQueuedBannerAttachmentFallback": "附件消息",
   "chatQueuedSubmitting": "正在加入队列…",
   "chatQueuedEdit": "编辑排队输入",

package/dist/assets/agents-nyTxTl89.js

@@ -1 +0,0 @@
-import{t as e}from"./agents-lT-bDFex.js";export{e as AgentsPage};