canopy-ui 0.6.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-ui",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "type": "module",
   "repository": {
     "type": "git",

package/src/chat/ChatPanel.pending.test.tsx

@@ -0,0 +1,136 @@
+/**
+ * Pressing send must change the TRANSCRIPT, not just the header.
+ *
+ * The gap this closes: no assistant row exists until `chat.stream_start`, and
+ * the server emits that together with `stream_complete` from one `assistant`
+ * ledger event (apps/canopy_sessions/stream_map.py) — i.e. only once the reply's
+ * first text exists, which on a laptop runner is a claim poll plus an emdash
+ * drive plus however long the agent thinks. So the conversation sat visibly
+ * unchanged for seconds-to-minutes after a send, which reads as the app having
+ * ignored you. Reported on a phone, twice, after the header-chip fix (#490)
+ * had supposedly addressed it.
+ */
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+
+import { ChatPanel } from "./ChatPanel";
+import type { Message, SessionState } from "./protocol";
+
+afterEach(cleanup);
+
+const ME = 1;
+
+function message(overrides: Partial<Message> = {}): Message {
+  return {
+    id: "m1",
+    turn_index: 1,
+    role: "user",
+    content: { text: "hi" },
+    plaintext: "hi",
+    status: "complete",
+    error_detail: null,
+    started_at: null,
+    completed_at: null,
+    created_at: "2026-07-30T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function state(overrides: Partial<SessionState> = {}): SessionState {
+  return {
+    messages: [message()],
+    active_draft: {
+      id: "d1",
+      body: "",
+      version: 1,
+      last_editor: ME,
+      last_edit_at: "2026-07-30T00:00:00Z",
+      slot: "next",
+      status: "open",
+    },
+    participants: [],
+    presence_user_ids: [ME],
+    current_user_id: ME,
+    ...overrides,
+  };
+}
+
+function panel(props: Partial<Parameters<typeof ChatPanel>[0]> = {}) {
+  return render(
+    <ChatPanel
+      state={state()}
+      connected
+      currentUserId={ME}
+      onSend={vi.fn()}
+      onStop={vi.fn()}
+      onUpdateDraft={vi.fn()}
+      onTakeOver={vi.fn()}
+      onDiscard={vi.fn()}
+      {...props}
+    />,
+  );
+}
+
+describe("the pending-reply row", () => {
+  it("is absent while nothing is outstanding", () => {
+    panel();
+    expect(screen.queryByTestId("pending-reply")).toBeNull();
+  });
+
+  it("appears the instant a send goes out, with no server round trip", () => {
+    // `awaitingReply` is set synchronously by sendChat. NOTHING server-side can
+    // answer sooner: the turn has to be enqueued, claimed, and driven into the
+    // agent before any report could exist.
+    panel({ awaitingReply: true });
+    expect(screen.getByTestId("pending-reply")).not.toBeNull();
+    expect(screen.getByText("Queued…")).not.toBeNull();
+  });
+
+  it("says the agent is thinking once the hook reports it started", () => {
+    // The distinction is the useful part: queued means canopy has not started
+    // your turn, thinking means the agent has it. Folding them together hides
+    // where the delay actually is.
+    panel({ state: state({ activity: "working" }), awaitingReply: false });
+    expect(screen.getByText("Thinking…")).not.toBeNull();
+  });
+
+  it("survives the first reply block, because the turn has not ended", () => {
+    // `awaitingReply` clears on the FIRST stream_complete, but the bridge posts
+    // each assistant block as its own event — so a turn that says one sentence
+    // and then works for another minute would otherwise go silent again.
+    panel({ state: state({ activity: "working" }), awaitingReply: false });
+    expect(screen.getByTestId("pending-reply")).not.toBeNull();
+  });
+
+  it("withdraws when the agent is BLOCKED on you", () => {
+    // The worst way to get this wrong: waiting on an agent that is waiting on
+    // you. `blocked` must never render as work in progress.
+    panel({ state: state({ activity: "blocked" }), awaitingReply: true });
+    expect(screen.queryByTestId("pending-reply")).toBeNull();
+  });
+
+  it("yields to a real assistant row once one exists", () => {
+    // Otherwise the reply and the placeholder are both on screen at once.
+    panel({
+      state: state({
+        messages: [
+          message(),
+          message({ id: "m2", turn_index: 2, role: "assistant", plaintext: "", content: {}, status: "streaming" }),
+        ],
+      }),
+      awaitingReply: true,
+    });
+    expect(screen.queryByTestId("pending-reply")).toBeNull();
+  });
+
+  it("shows on a first-ever send, when the empty state would otherwise win", () => {
+    panel({
+      state: state({ messages: [] }),
+      awaitingReply: true,
+      emptyState: <div>no messages yet</div>,
+    });
+    expect(screen.getByTestId("pending-reply")).not.toBeNull();
+    expect(screen.queryByText("no messages yet")).toBeNull();
+  });
+});

package/src/chat/ChatPanel.tsx

@@ -6,7 +6,7 @@ import { ConnectionStatus } from "./ConnectionStatus";
 import { MessageList } from "./MessageList";
 import { PresenceChips } from "./PresenceChips";
 import { SendBox, type PendingAttachment } from "./SendBox";
-import { isDraftIdle, msUntilDraftIdle } from "./drafts";
+import { isDraftIdle, msUntilDraftIdle, type DraftStorage } from "./drafts";
 import { useStickyBottom } from "./useStickyBottom";
 
 export interface ChatPanelProps {
@@ -34,6 +34,11 @@ export interface ChatPanelProps {
   disabledReason?: string;
   /** Rendered at the top of the scroll container (e.g. a "Load earlier" button / offline banner). */
   historySlot?: ReactNode;
+  /** Persist the half-typed composer body under this key (the session id) so
+   *  it survives routing away and back. Omit for in-memory-only drafts. */
+  draftPersistKey?: string;
+  /** Storage backing `draftPersistKey`; defaults to localStorage. */
+  draftStorage?: DraftStorage | null;
 }
 
 /**
@@ -60,6 +65,8 @@ export function ChatPanel({
   emptyState,
   disabledReason,
   historySlot,
+  draftPersistKey,
+  draftStorage,
 }: ChatPanelProps) {
   // `onDiscard` is part of the public surface (co-edit teardown) even though
   // the default composer doesn't render a discard button. Referenced to keep
@@ -82,6 +89,14 @@ export function ChatPanel({
   const holderId = state.active_draft?.last_editor ?? null;
   const holderIsPresent =
     holderId != null && state.presence_user_ids.includes(holderId);
+  // The holder's NAME, for the composer. SendBox has ids and no roster, so
+  // without this the one place a person actually looks — the box their
+  // teammate's words are appearing in — could only say "Another teammate",
+  // while the name sat in a chip at the far corner of the screen.
+  const holderName =
+    holderId != null && holderId !== currentUserId
+      ? (state.participants.find((p) => p.user_id === holderId)?.display_name ?? null)
+      : null;
 
   // A turn is "in flight" from the moment the assistant row appears
   // (status=pending/streaming) until chat.stream_complete flips it to
@@ -96,13 +111,37 @@ export function ChatPanel({
     [state.messages],
   );
 
+  // Feedback where the eye actually is. Pressing send used to change NOTHING in
+  // the transcript: no assistant row exists until `chat.stream_start`, which the
+  // server emits together with `stream_complete` from a single `assistant`
+  // ledger event — i.e. only once the reply's first TEXT exists, seconds to
+  // minutes later. So MessageItem's own "Thinking…" treatment was unreachable on
+  // the real runner path, and the only signal was a 12px chip in the header,
+  // which on a phone is the far corner of the screen from your thumb.
+  //
+  // Two sources, deliberately: `awaitingReply` is client-side and answers
+  // INSTANTLY with no round trip (nothing server-side can — the turn has to be
+  // enqueued, claimed and driven into the agent before anything could report),
+  // and `activity === "working"` keeps it up for the rest of the turn, across
+  // the gaps between the assistant's separate text blocks. `blocked` withdraws
+  // it: an agent waiting on YOU must never render as an agent working.
+  const agentHasFloor =
+    state.activity !== "blocked" &&
+    (awaitingReply || state.activity === "working");
+  const showPendingReply = inFlightMessage == null && agentHasFloor;
+  // "Queued" until something reports the agent actually started — the useful
+  // distinction is where the delay is, not that there is one.
+  const pendingLabel = state.activity === "working" ? "Thinking…" : "Queued…";
+
   // Sticky-bottom scroll: dep changes on (a) new message arrival and (b)
   // streaming text growth on the last message. length-only (cheap) instead
   // of the full string so the effect doesn't re-run on equal characters.
+  // `showPendingReply` is in the dep too — the bubble is a new row at the
+  // bottom, and appearing below the fold would defeat the whole point of it.
   const messages = state.messages;
   const lastMessageLen =
     messages.length > 0 ? messages[messages.length - 1].plaintext.length : 0;
-  const scrollDep = `${messages.length}:${lastMessageLen}`;
+  const scrollDep = `${messages.length}:${lastMessageLen}:${showPendingReply}`;
   const { containerRef, onScroll } = useStickyBottom(scrollDep);
 
   return (
@@ -115,6 +154,7 @@ export function ChatPanel({
             presenceUserIds={state.presence_user_ids}
             draftHolderId={holderId}
             draftHolderIdle={isDraftIdle(state.active_draft)}
+            currentUserId={currentUserId}
           />
         </div>
       </div>
@@ -131,6 +171,8 @@ export function ChatPanel({
           messages={state.messages}
           emptyState={emptyState}
           renderMarkdown={renderMarkdown}
+          pendingReply={showPendingReply}
+          pendingLabel={pendingLabel}
         />
       </div>
       <SendBox
@@ -138,17 +180,21 @@ export function ChatPanel({
         connected={connected}
         currentUserId={currentUserId}
         holderIsPresent={holderIsPresent}
+        holderName={holderName}
         isStreaming={inFlightMessage != null || awaitingReply}
         streamingMessageId={inFlightMessage?.id ?? null}
         onUpdate={onUpdateDraft}
         onSend={onSend}
         onStop={onStop}
+        stopState={state.stopState}
         onTakeOver={onTakeOver}
         banner={banner}
         disabledReason={disabledReason}
         attachments={attachments}
         onAttach={onAttach}
         onRemoveAttachment={onRemoveAttachment}
+        persistKey={draftPersistKey}
+        storage={draftStorage}
       />
     </div>
   );

package/src/chat/MenuPrompt.test.tsx

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { menuAge } from "./MenuPrompt";
+import type { SessionMenu } from "./protocol";
+
+const base: SessionMenu = { question: "Pick one", options: [{ number: 1, label: "A" }] };
+
+describe("menuAge", () => {
+  it("says nothing while the dialog is fresh", () => {
+    // The runner re-reports every ~10s, so recent lag is normal and naming it
+    // would make every menu look doubtful.
+    expect(menuAge({ ...base, observed_at: 1_000 }, 1_000_000 + 30_000)).toBe("");
+  });
+
+  it("shows an age once nobody has confirmed it lately", () => {
+    const now = 1_000_000_000_000;
+    expect(menuAge({ ...base, observed_at: now / 1000 - 600 }, now)).toBe("last seen 10m ago");
+    expect(menuAge({ ...base, observed_at: now / 1000 - 7200 }, now)).toBe("last seen 2h ago");
+  });
+
+  it("says nothing when the producer did not stamp", () => {
+    // Pre-`observed_at` rows exist; an unstamped menu must not read as ancient.
+    expect(menuAge(base, Date.now())).toBe("");
+  });
+});

package/src/chat/MenuPrompt.tsx

@@ -1,10 +1,55 @@
-import type { SessionMenu } from "./protocol";
+import { useMemo, useState } from "react";
+import type { MenuQuestion, SessionMenu } from "./protocol";
 
 export interface MenuPromptProps {
   menu: SessionMenu;
   busy?: boolean;
   error?: string;
-  onAnswer: (option: number | null) => void;
+  /** `selections` is the whole answer — one list of chosen option numbers per
+   *  question. Omitted for the single-question single-select dialogs that a
+   *  lone `option` has always been able to answer.
+   *
+   *  `texts` carries the answer that is NOT on the menu, per question. The TUI
+   *  appends a "Type something" row to every question, and it is frequently
+   *  where the real answer goes — the July closeout's notes were all typed, not
+   *  picked. Without it a phone can only choose from what the agent guessed. */
+  onAnswer: (
+    option: number | null,
+    selections?: number[][] | null,
+    texts?: (string | null)[] | null,
+  ) => void;
+  /** Injectable for tests; defaults to the wall clock. */
+  now?: number;
+}
+
+/** Whether this ask needs the full form rather than a row of buttons.
+ *
+ *  One single-select question is the shape a lone keypress answers, and it is
+ *  the overwhelmingly common one — a permission prompt, a yes/no. Anything else
+ *  (several questions, or one that takes several answers) cannot be completed by
+ *  pressing a single button, so rendering buttons for it is a lie. */
+export function needsForm(menu: SessionMenu): boolean {
+  const qs = menu.questions;
+  if (!qs || qs.length === 0) return false;
+  return qs.length > 1 || qs.some((q) => q.multi_select);
+}
+
+function isAnswered(picks: number[] | undefined): boolean {
+  return Boolean(picks && picks.length > 0);
+}
+
+/** How old a dialog may be before we say so. The runner re-reports every ~10s,
+ *  so anything past a couple of minutes is not merely lagging — it is a dialog
+ *  nobody has confirmed lately, and the honest thing is to show its age rather
+ *  than let a confident-looking button be the way you discover it. */
+const STALE_AFTER_MS = 120_000;
+
+export function menuAge(menu: SessionMenu, now: number): string {
+  if (!menu.observed_at) return "";
+  const ms = now - menu.observed_at * 1000;
+  if (ms < STALE_AFTER_MS) return "";
+  const mins = Math.round(ms / 60_000);
+  return mins < 60 ? `last seen ${mins}m ago` : `last seen ${Math.round(mins / 60)}h ago`;
 }
 
 /**
@@ -17,32 +62,258 @@ export interface MenuPromptProps {
  * Refusing is always offered separately from the numbered options. Every dialog
  * accepts Escape, and it is the only answer that stays correct if the dialog on
  * screen is not the one rendered here.
+ *
+ * A tap that was relayed and then refused BY THE RUNNER comes back as
+ * `menu.answer_note`, and it wins over the local `error` prop because it is the
+ * later, more specific half of the same story: `error` means the server would
+ * not relay the tap, `answer_note` means it did and the keystroke still did not
+ * land. Showing neither is what made this button look dead for 45 minutes — the
+ * API answers `ok:true` the instant it relays, so silence read as success.
+ *
+ * The options render in one of two shapes, chosen by whether the dialog carries
+ * descriptions. A permission prompt's options ("Yes" / "No") are a row of chips.
+ * An AskUserQuestion's are not: its descriptions are the decision itself — on
+ * the run that motivated this, "Proceed to Phase 4" and "Stop the run here"
+ * were separated entirely by prose the labels did not contain (that Phase 4 is
+ * test-gated and reaches no real payment). Rendering those as bare chips asks
+ * somebody to choose blind, which is the same failure as showing no menu, only
+ * quieter.
+ */
+/** Every question at once, answered in one go.
+ *
+ *  Deliberately NOT a tab strip mirroring the terminal's. The terminal shows one
+ *  question at a time because it has one screen and a cursor; a phone has a
+ *  scroll, and the thing that actually went wrong was somebody answering what
+ *  looked like the whole ask and it turning out to be tab 2 of 3. Showing all of
+ *  them, with one Send at the end, makes "have I finished?" answerable by
+ *  looking — which is the only question this surface has ever got wrong.
  */
-export function MenuPrompt({ menu, busy = false, error, onAnswer }: MenuPromptProps) {
+function AnswerForm({
+  menu,
+  questions,
+  busy,
+  onAnswer,
+}: {
+  menu: SessionMenu;
+  questions: MenuQuestion[];
+  busy: boolean;
+  onAnswer: MenuPromptProps["onAnswer"];
+}) {
+  const [picks, setPicks] = useState<Record<number, number[]>>({});
+  const [typed, setTyped] = useState<Record<number, string>>({});
+
+  const toggle = (q: MenuQuestion, number: number) => {
+    setPicks((prev) => {
+      const current = prev[q.index] ?? [];
+      if (!q.multi_select) return { ...prev, [q.index]: [number] };
+      return {
+        ...prev,
+        [q.index]: current.includes(number)
+          ? current.filter((n) => n !== number)
+          : [...current, number].sort((a, b) => a - b),
+      };
+    });
+  };
+
+  // Typing your own answer to a SINGLE-select question replaces the pick,
+  // because that is what the TUI does — selecting "Type something" moves the
+  // selection onto the text row. On a multi-select the text is an extra
+  // checkbox, so both can stand.
+  const write = (q: MenuQuestion, value: string) => {
+    setTyped((prev) => ({ ...prev, [q.index]: value }));
+    if (!q.multi_select && value.trim()) {
+      setPicks((prev) => ({ ...prev, [q.index]: [] }));
+    }
+  };
+
+  const answered = (q: MenuQuestion) =>
+    isAnswered(picks[q.index]) || Boolean((typed[q.index] ?? "").trim());
+
+  const remaining = useMemo(
+    () => questions.filter((q) => !answered(q)).length,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [questions, picks, typed],
+  );
+
+  const send = () => {
+    // Positional, and every question gets an entry even when unanswered: the
+    // runner walks the tabs in this order, so a missing entry would silently
+    // shift every later answer onto the wrong question.
+    const selections = questions.map((q) => picks[q.index] ?? []);
+    const texts = questions.map((q) => (typed[q.index] ?? "").trim() || null);
+    // `option` is the first pick, for a runner too old to read `selections`.
+    // Sending null there would read as "refuse" and cancel the dialog.
+    onAnswer(selections[0]?.[0] ?? null, selections, texts);
+  };
+
+  return (
+    <div className="mt-2 flex flex-col gap-3">
+      {questions.map((q) => (
+        <div key={q.index}>
+          <div className="text-[12px] font-medium uppercase tracking-wide text-muted-foreground">
+            {q.header || `Question ${q.index + 1}`}
+            {q.multi_select ? " · pick any" : ""}
+          </div>
+          <div className="mt-0.5 text-[13px] text-foreground">{q.question}</div>
+          <div className="mt-1.5 flex flex-col gap-1">
+            {q.options.map((option) => {
+              const on = (picks[q.index] ?? []).includes(option.number);
+              return (
+                <button
+                  key={option.number}
+                  type="button"
+                  disabled={busy}
+                  aria-pressed={on}
+                  onClick={() => toggle(q, option.number)}
+                  className={`flex items-start gap-2 rounded border px-2.5 py-2 text-left disabled:opacity-50 ${
+                    on ? "border-warning bg-warning/10" : "border-input bg-card hover:bg-muted"
+                  }`}
+                >
+                  <span aria-hidden className="mt-[1px] shrink-0 text-[13px]">
+                    {on ? (q.multi_select ? "☑" : "◉") : q.multi_select ? "☐" : "○"}
+                  </span>
+                  <span>
+                    <span className="block text-[13px] font-medium text-foreground">
+                      {option.label}
+                    </span>
+                    {option.description ? (
+                      <span className="mt-0.5 block text-[12px] leading-snug text-muted-foreground">
+                        {option.description}
+                      </span>
+                    ) : null}
+                  </span>
+                </button>
+              );
+            })}
+            {/* The answer that is not on the menu. The terminal offers this on
+                every question ("Type something"), and it is where the real
+                answer often goes, so a phone without it can only pick from what
+                the agent happened to guess.
+ */}
+            <input
+              type="text"
+              value={typed[q.index] ?? ""}
+              disabled={busy}
+              onChange={(e) => write(q, e.target.value)}
+              placeholder="…or type your own answer"
+              className="mt-0.5 rounded border border-input bg-card px-2.5 py-2 text-[13px] text-foreground placeholder:text-muted-foreground disabled:opacity-50"
+            />
+          </div>
+        </div>
+      ))}
+      <div className="flex flex-wrap items-center gap-2">
+        <button
+          type="button"
+          // Sendable as soon as ANYTHING is answered, not only when everything
+          // is. The terminal submits a partly-filled ask and merely warns, and
+          // refusing here made a question you meant to skip unskippable from a
+          // phone. Still not sendable when NOTHING is answered — that is what
+          // Cancel says, and says better.
+          disabled={busy || remaining === questions.length}
+          onClick={send}
+          className="rounded bg-warning px-3 py-1.5 text-[13px] font-medium text-warning-foreground disabled:opacity-50"
+        >
+          {busy ? "Sending…" : "Send answers"}
+        </button>
+        {remaining > 0 ? (
+          <span className="text-[12px] text-muted-foreground">
+            {remaining === questions.length
+              ? "answer at least one to send"
+              : `${remaining} unanswered — will send anyway`}
+          </span>
+        ) : null}
+      </div>
+      {menu.body ? (
+        <div className="text-[12px] text-muted-foreground">{menu.body}</div>
+      ) : null}
+    </div>
+  );
+}
+
+export function MenuPrompt({ menu, busy = false, error, onAnswer, now = Date.now() }: MenuPromptProps) {
+  const described = menu.options.some((o) => o.description);
+  // A dialog Claude Code drew with no tool call behind it — a permission prompt,
+  // a trust gate. The `Notification` hook says a human is wanted and carries a
+  // message, but no options: reading those means driving CDP, which steals
+  // focus, so they are genuinely not available here. Saying so beats an empty
+  // box, and beats the previous behaviour of showing nothing at all.
+  //
+  // Escape is still REAL on one of these: the runner re-reads the actual screen
+  // before pressing anything, and a permission prompt parses there — so the
+  // refuse button below is an action, not a placeholder. When the screen turns
+  // out to be an ordinary prompt, that same re-read answers NO_DIALOG and the
+  // marker is dropped, which is the way out of a marker that was never a dialog.
+  //
+  // It may also not be a dialog at all — nothing was parsed to produce this, so
+  // the copy no longer promises one is there. The composer stays live behind it
+  // for the same reason (`menuBlocksComposer`).
+  const optionless = menu.options.length === 0;
+  const age = menuAge(menu, now);
+  const form = needsForm(menu);
   return (
     <div className="rounded-md border border-warning/30 bg-warning/10 px-3 py-2.5 text-sm">
       <div className="flex items-center gap-1.5 font-medium text-warning">
         <span className="inline-block h-1.5 w-1.5 animate-pulse rounded-full bg-warning" />
         {menu.title || "Waiting on you"}
+        {age ? (
+          <span className="ml-auto text-[11px] font-normal text-muted-foreground">{age}</span>
+        ) : null}
       </div>
-      {menu.body ? (
+      {menu.body && !form ? (
         <pre className="mt-1.5 max-h-32 overflow-auto whitespace-pre-wrap break-all rounded bg-muted px-2 py-1.5 font-mono text-[12px] text-foreground-secondary">
           {menu.body}
         </pre>
       ) : null}
-      <div className="mt-2 text-foreground">{menu.question}</div>
-      <div className="mt-2 flex flex-wrap gap-1.5">
-        {menu.options.map((option) => (
-          <button
-            key={option.number}
-            type="button"
-            disabled={busy}
-            onClick={() => onAnswer(option.number)}
-            className="rounded border border-input bg-card px-2 py-1 text-[13px] text-foreground hover:bg-muted disabled:opacity-50"
-          >
-            {option.label}
-          </button>
-        ))}
+      {/* The form prints each question against its own options, so the single
+          top-level question would be question 1 shown twice. */}
+      {form ? null : <div className="mt-2 text-foreground">{menu.question}</div>}
+      {form ? (
+        <AnswerForm
+          menu={menu}
+          questions={menu.questions ?? []}
+          busy={busy}
+          onAnswer={onAnswer}
+        />
+      ) : optionless ? (
+        <div className="mt-1.5 text-[12px] leading-snug text-muted-foreground">
+          No options came with this one — open the session in emdash to see what is on
+          screen. Cancelling clears it if nothing is, and the composer below still sends.
+        </div>
+      ) : described ? (
+        <div className="mt-2 flex flex-col gap-1.5">
+          {menu.options.map((option) => (
+            <button
+              key={option.number}
+              type="button"
+              disabled={busy}
+              onClick={() => onAnswer(option.number)}
+              className="rounded border border-input bg-card px-2.5 py-2 text-left hover:bg-muted disabled:opacity-50"
+            >
+              <div className="text-[13px] font-medium text-foreground">{option.label}</div>
+              {option.description ? (
+                <div className="mt-0.5 text-[12px] leading-snug text-muted-foreground">
+                  {option.description}
+                </div>
+              ) : null}
+            </button>
+          ))}
+        </div>
+      ) : (
+        <div className="mt-2 flex flex-wrap gap-1.5">
+          {menu.options.map((option) => (
+            <button
+              key={option.number}
+              type="button"
+              disabled={busy}
+              onClick={() => onAnswer(option.number)}
+              className="rounded border border-input bg-card px-2 py-1 text-[13px] text-foreground hover:bg-muted disabled:opacity-50"
+            >
+              {option.label}
+            </button>
+          ))}
+        </div>
+      )}
+      <div className="mt-2">
         <button
           type="button"
           disabled={busy}
@@ -52,7 +323,9 @@ export function MenuPrompt({ menu, busy = false, error, onAnswer }: MenuPromptPr
           Cancel (Esc)
         </button>
       </div>
-      {error ? <div className="mt-1.5 text-[12px] text-destructive">{error}</div> : null}
+      {menu.answer_note || error ? (
+        <div className="mt-1.5 text-[12px] text-destructive">{menu.answer_note || error}</div>
+      ) : null}
     </div>
   );
 }

package/src/chat/MessageItem.tsx

@@ -44,6 +44,26 @@ function classifyError(detail: string | null) {
   };
 }
 
+/**
+ * The animated "the agent has the floor" treatment.
+ *
+ * Exported because it is rendered from two places that must not drift: inside a
+ * real assistant row that has started but has no text yet, and as MessageList's
+ * TRAILING row while no assistant row exists at all (see `pendingReply` there).
+ */
+export function ThinkingIndicator({ label = "Thinking…" }: { label?: string }) {
+  return (
+    <span className="inline-flex items-center gap-1.5 text-muted-foreground">
+      <span className="inline-flex gap-0.5" aria-label="thinking">
+        <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current [animation-delay:-0.3s]" />
+        <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current [animation-delay:-0.15s]" />
+        <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current" />
+      </span>
+      <span className="text-xs italic">{label}</span>
+    </span>
+  );
+}
+
 export function MessageItem({
   message,
   forceToolOpen,
@@ -104,14 +124,7 @@ export function MessageItem({
       aria-live={isStreaming || isPending ? "polite" : undefined}
     >
       {showThinking ? (
-        <span className="inline-flex items-center gap-1.5 text-muted-foreground">
-          <span className="inline-flex gap-0.5" aria-label="thinking">
-            <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current [animation-delay:-0.3s]" />
-            <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current [animation-delay:-0.15s]" />
-            <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current" />
-          </span>
-          <span className="text-xs italic">Thinking…</span>
-        </span>
+        <ThinkingIndicator />
       ) : message.role === "assistant" ? (
         renderMarkdown(text)
       ) : (