@carlonicora/nextjs-jsonapi 3.23.0 → 3.24.0

package/src/features/assistant/components/parts/AssistantComposer.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, type KeyboardEvent } from "react";
+import { useState, type KeyboardEvent, type ReactNode } from "react";
 import { useTranslations } from "next-intl";
 import { ArrowUp } from "lucide-react";
 import { Button, Textarea } from "../../../../shadcnui";
@@ -22,6 +22,11 @@ interface Props {
    * move.
    */
   sendLabel?: string;
+  /**
+   * Rendered at the bottom-left of the input box, opposite the send button
+   * (e.g. a scope picker). When omitted the box keeps its single-row layout.
+   */
+  leading?: ReactNode;
 }
 
 export function AssistantComposer({
@@ -31,6 +36,7 @@ export function AssistantComposer({
   onValueChange,
   placeholder,
   sendLabel,
+  leading,
 }: Props) {
   const t = useTranslations();
   const [internal, setInternal] = useState("");
@@ -53,22 +59,39 @@ export function AssistantComposer({
     }
   };
 
+  const textarea = (
+    <Textarea
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      onKeyDown={onKeyDown}
+      placeholder={placeholder ?? t("features.assistant.composer_placeholder")}
+      disabled={disabled}
+      rows={2}
+      className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
+    />
+  );
+  const sendButton = (
+    <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
+      <ArrowUp className="me-1 h-4 w-4" /> {sendLabel ?? t("features.assistant.send")}
+    </Button>
+  );
+
   return (
     <div className="flex flex-col gap-1 border-t p-4">
-      <div className="bg-muted/30 flex items-end gap-2 rounded-lg border p-2">
-        <Textarea
-          value={value}
-          onChange={(e) => setValue(e.target.value)}
-          onKeyDown={onKeyDown}
-          placeholder={placeholder ?? t("features.assistant.composer_placeholder")}
-          disabled={disabled}
-          rows={2}
-          className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
-        />
-        <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
-          <ArrowUp className="me-1 h-4 w-4" /> {sendLabel ?? t("features.assistant.send")}
-        </Button>
-      </div>
+      {leading ? (
+        <div className="bg-muted/30 flex flex-col gap-2 rounded-lg border p-2">
+          {textarea}
+          <div className="flex items-center justify-between gap-2">
+            <div className="min-w-0">{leading}</div>
+            {sendButton}
+          </div>
+        </div>
+      ) : (
+        <div className="bg-muted/30 flex items-end gap-2 rounded-lg border p-2">
+          {textarea}
+          {sendButton}
+        </div>
+      )}
       <div className="text-muted-foreground text-end text-xs">{t("features.assistant.keyboard_hint")}</div>
     </div>
   );

package/src/features/assistant/components/parts/AssistantEmptyState.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useState, type ReactNode } from "react";
 import { useTranslations } from "next-intl";
 import { Sparkles } from "lucide-react";
 import { Label, Switch } from "../../../../shadcnui";
@@ -16,11 +16,13 @@ interface Props {
    */
   operatorMode?: boolean;
   onOperatorModeChange?: (value: boolean) => void;
+  /** Rendered inside the composer, bottom-left (e.g. a scope picker). */
+  composerLeading?: ReactNode;
 }
 
 const STARTER_KEYS = ["a", "b", "c", "d"] as const;
 
-export function AssistantEmptyState({ onSend, operatorMode = false, onOperatorModeChange }: Props) {
+export function AssistantEmptyState({ onSend, operatorMode = false, onOperatorModeChange, composerLeading }: Props) {
   const t = useTranslations();
   const [draft, setDraft] = useState("");
 
@@ -34,7 +36,7 @@ export function AssistantEmptyState({ onSend, operatorMode = false, onOperatorMo
           <SectionHeader>{t("features.assistant.empty_state.title")}</SectionHeader>
           <p className="text-muted-foreground mt-1 text-sm">{t("features.assistant.empty_state.subtitle")}</p>
         </div>
-        <AssistantComposer value={draft} onValueChange={setDraft} onSend={onSend} />
+        <AssistantComposer value={draft} onValueChange={setDraft} onSend={onSend} leading={composerLeading} />
         {onOperatorModeChange && (
           <div className="flex items-center justify-end gap-2">
             <Switch

package/src/features/assistant/components/parts/AssistantSidebar.tsx

@@ -2,6 +2,7 @@
 
 import { useTranslations } from "next-intl";
 import { Plus } from "lucide-react";
+import type { ReactNode } from "react";
 import { Button } from "../../../../shadcnui";
 import { MicroLabel } from "../../../../components/typography";
 import type { AssistantInterface } from "../../data/AssistantInterface";
@@ -11,7 +12,12 @@ interface Props {
   threads: AssistantInterface[];
   activeId?: string;
   onSelect: (id: string) => void;
-  onNew: () => void;
+  /**
+   * Starts a new thread. Omit it when the host renders the "new" action
+   * elsewhere (the `/assistants` page puts it in the page header), and the
+   * sidebar then shows only the thread list.
+   */
+  onNew?: () => void;
   /**
    * Label of the "start a new thread" button. Defaults to the assistant's own
    * copy; a surface that is not the assistant (the handbook chat) passes its
@@ -20,9 +26,19 @@ interface Props {
   newLabel?: string;
   /** Shown when there are no threads. Same rationale as `newLabel`. */
   emptyLabel?: string;
+  /** Optional badge rendered inside each thread button, after the title (e.g. the thread's scope). */
+  renderThreadBadge?: (thread: AssistantInterface) => ReactNode;
 }
 
-export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel, emptyLabel }: Props) {
+export function AssistantSidebar({
+  threads,
+  activeId,
+  onSelect,
+  onNew,
+  newLabel,
+  emptyLabel,
+  renderThreadBadge,
+}: Props) {
   const t = useTranslations();
   const groups = groupThreadsByBucket(threads);
 
@@ -42,6 +58,7 @@ export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel,
             }
           >
             {thread.title}
+            {renderThreadBadge?.(thread)}
           </button>
         ))}
       </div>
@@ -50,11 +67,13 @@ export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel,
 
   return (
     <aside className="bg-muted/30 flex w-64 flex-col border-e">
-      <div className="border-b p-3">
-        <Button onClick={onNew} className="w-full" size="sm">
-          <Plus className="me-1 h-4 w-4" /> {newLabel ?? t("features.assistant.new")}
-        </Button>
-      </div>
+      {onNew && (
+        <div className="border-b p-3">
+          <Button onClick={onNew} className="w-full" size="sm">
+            <Plus className="me-1 h-4 w-4" /> {newLabel ?? t("features.assistant.new")}
+          </Button>
+        </div>
+      )}
       <div className="flex-1 overflow-y-auto p-2">
         {threads.length === 0 ? (
           <div className="text-muted-foreground mt-6 text-center text-xs">

package/src/features/assistant/components/parts/__tests__/AssistantComposer.spec.tsx

@@ -29,4 +29,12 @@ describe("AssistantComposer", () => {
     const send = screen.getByRole("button", { name: /features\.assistant\.send/i });
     expect(send).toBeDisabled();
   });
+
+  it("renders the leading slot inside the input box, before the send button", () => {
+    render(<AssistantComposer onSend={vi.fn()} leading={<span data-testid="leading-slot" />} />);
+    const slot = screen.getByTestId("leading-slot");
+    const send = screen.getByRole("button", { name: /features\.assistant\.send/i });
+    expect(slot.compareDocumentPosition(send) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(slot.closest(".rounded-lg")).toBe(send.closest(".rounded-lg"));
+  });
 });

package/src/features/assistant/components/parts/__tests__/AssistantSidebar.spec.tsx

@@ -55,4 +55,11 @@ describe("AssistantSidebar", () => {
     await userEvent.click(screen.getByRole("button", { name: /^T$/ }));
     expect(onSelect).toHaveBeenCalledWith("a1");
   });
+
+  it("without onNew renders no new button", () => {
+    const threads = [buildAssistantStub({ id: "a1", title: "T", updatedAt: new Date("2026-04-22T09:00:00Z") })];
+    render(<AssistantSidebar threads={threads} onSelect={vi.fn()} />);
+    expect(screen.queryByRole("button", { name: /features\.assistant\.new/ })).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /^T$/ })).toBeInTheDocument();
+  });
 });

package/src/features/assistant/contexts/AssistantContext.tsx

@@ -1,8 +1,10 @@
 "use client";
 
+import { PlusCircleIcon } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { SharedProvider } from "../../../contexts";
+import { Button } from "../../../shadcnui";
 import { useSocketContext } from "../../../contexts/SocketContext";
 import { BreadcrumbItemData, JsonApiHydratedDataInterface, Modules, rehydrate, rehydrateList } from "../../../core";
 import { usePageUrlGenerator } from "../../../hooks";
@@ -40,6 +42,10 @@ interface AssistantContextValue {
   setOperatorMode(value: boolean): void;
   /** Appends a message returned outside the send flow (e.g. an approve/deny resume). */
   appendResolvedMessage(message: AssistantMessageInterface): void;
+  /** The scope a NEW thread will bind to. Starts from the provider's `scope` prop. */
+  scope?: { type: string; id: string };
+  /** Changes the scope a new thread binds to. Ignored once a thread is active. */
+  setScope(scope?: { type: string; id: string }): void;
 }
 
 const AssistantContext = createContext<AssistantContextValue | undefined>(undefined);
@@ -141,6 +147,9 @@ export function AssistantProvider({
   const [operatorMode, setOperatorMode] = useState<boolean>(
     () => dehydratedAssistant?.jsonApi?.attributes?.engine === "operator",
   );
+  // The scope the next created thread binds to. Starts from the `scope` prop
+  // and can be changed by the host (e.g. a scope picker) until a thread exists.
+  const [pendingScope, setPendingScope] = useState<{ type: string; id: string } | undefined>(scope);
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
@@ -172,6 +181,35 @@ export function AssistantProvider({
       };
       socket?.on("assistant:status", handler);
 
+      // A new thread is named and persisted before its answer runs; the server
+      // announces it on `assistant:created` so the thread list and the URL
+      // update immediately instead of when the long create request returns.
+      let createdHandled = false;
+      const createdHandler = (payload: {
+        assistant?: { data?: JsonApiHydratedDataInterface["jsonApi"]; included?: any[] };
+      }) => {
+        if (createdHandled) return;
+        const data = payload?.assistant?.data;
+        if (!data || typeof data !== "object" || typeof data.id !== "string" || !data.id) return;
+        let thread: AssistantInterface;
+        try {
+          thread = rehydrate<AssistantInterface>(Modules.Assistant, {
+            jsonApi: data,
+            included: payload.assistant?.included ?? [],
+          });
+        } catch {
+          return;
+        }
+        if (!thread?.id) return;
+        createdHandled = true;
+        setAssistant(thread);
+        setThreads((prev) => [thread, ...prev.filter((row) => row.id !== thread.id)]);
+        if (manageUrl && typeof window !== "undefined") {
+          window.history.replaceState(null, "", resolveThreadUrl(thread.id));
+        }
+      };
+      if (!assistant) socket?.on("assistant:created", createdHandler);
+
       try {
         if (!assistant) {
           const input = {
@@ -181,7 +219,7 @@ export function AssistantProvider({
             handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
             limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
             contentBlocks: opts?.contentBlocks,
-            boundContent: scope,
+            boundContent: pendingScope,
           };
           const created = operatorMode
             ? await AssistantService.createOperator(input)
@@ -189,7 +227,11 @@ export function AssistantProvider({
           const msgs = await AssistantMessageService.findByAssistant({ assistantId: created.id });
           setAssistant(created);
           setMessages(msgs);
-          setThreads((prev) => [created, ...prev]);
+          setThreads((prev) =>
+            prev.some((row) => row.id === created.id)
+              ? prev.map((row) => (row.id === created.id ? created : row))
+              : [created, ...prev],
+          );
           if (manageUrl && typeof window !== "undefined") {
             window.history.replaceState(null, "", resolveThreadUrl(created.id));
           }
@@ -219,11 +261,12 @@ export function AssistantProvider({
         });
       } finally {
         socket?.off("assistant:status", handler);
+        if (!assistant) socket?.off("assistant:created", createdHandler);
         setSending(false);
         setStatus(undefined);
       }
     },
-    [assistant, messages, socket, operatorMode, scope, retrievalMode, manageUrl, resolveThreadUrl],
+    [assistant, messages, socket, operatorMode, pendingScope, retrievalMode, manageUrl, resolveThreadUrl],
   );
 
   const appendResolvedMessage = useCallback((message: AssistantMessageInterface) => {
@@ -278,10 +321,20 @@ export function AssistantProvider({
     setMessages([]);
     setFailedMessageIds(new Set());
     setOperatorMode(false);
+    setPendingScope(scope);
     if (manageUrl && typeof window !== "undefined") {
       window.history.replaceState(null, "", resolveThreadUrl());
     }
-  }, [manageUrl, resolveThreadUrl]);
+  }, [manageUrl, resolveThreadUrl, scope]);
+
+  const setScope = useCallback(
+    (next?: { type: string; id: string }) => {
+      // An existing thread is already bound; its scope cannot change.
+      if (assistant) return;
+      setPendingScope(next);
+    },
+    [assistant],
+  );
 
   const deleteThread = useCallback(async (id: string) => {
     await AssistantService.delete({ id });
@@ -329,6 +382,8 @@ export function AssistantProvider({
       operatorMode,
       setOperatorMode,
       appendResolvedMessage,
+      scope: pendingScope,
+      setScope,
     }),
     [
       assistant,
@@ -346,6 +401,8 @@ export function AssistantProvider({
       deleteThread,
       operatorMode,
       appendResolvedMessage,
+      pendingScope,
+      setScope,
     ],
   );
 
@@ -360,9 +417,36 @@ export function AssistantProvider({
 
   // `entities.tasks` was a copy-paste from another feature and rendered
   // "Tasks" as the page heading of every assistant page.
-  const title = {
-    type: titleOverride ?? t("entities.assistants", { count: 2 }),
-  };
+  // Shaped like the conversations page heading: the open thread's title as the
+  // element, and the new-thread action in the shared header so it stays
+  // reachable when the thread-list panel is collapsed.
+  const title = useMemo(() => {
+    const response: { type: string; element?: string; functions?: React.ReactNode } = {
+      type: titleOverride ?? t("entities.assistants", { count: assistant ? 1 : 2 }),
+    };
+
+    if (assistant?.title) {
+      response.element = assistant.title.length > 25 ? `${assistant.title.substring(0, 25)}...` : assistant.title;
+    }
+
+    response.functions = [
+      <Button
+        key="new-assistant"
+        data-testid="assistant-new-button"
+        size="sm"
+        variant={`outline`}
+        onClick={(e) => {
+          e.preventDefault();
+          startNew();
+        }}
+      >
+        <PlusCircleIcon className="me-2 h-3.5 w-3.5" />
+        {t("features.assistant.new")}
+      </Button>,
+    ];
+
+    return response;
+  }, [assistant, startNew, t, titleOverride]);
 
   return (
     <AssistantContext.Provider value={value}>

package/src/features/assistant/contexts/__tests__/AssistantContext.spec.tsx

@@ -4,6 +4,8 @@ import { AssistantProvider, useAssistantContext } from "../AssistantContext";
 import { AssistantService } from "../../data/AssistantService";
 import { AssistantMessageService } from "../../../assistant-message/data/AssistantMessageService";
 import { useSocketContext } from "../../../../contexts/SocketContext";
+import { useSharedContext } from "../../../../contexts";
+import { render, screen, fireEvent } from "@testing-library/react";
 import type { JsonApiHydratedDataInterface } from "../../../../core";
 import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
 import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
@@ -636,4 +638,198 @@ describe("AssistantContext", () => {
 
     replaceState.mockRestore();
   });
+
+  it("setScope binds the first message's thread", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const create = vi.fn().mockResolvedValue(buildAssistantStub({ id: "a-scoped" }));
+    AssistantService.create = create;
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    expect(result.current.scope).toBeUndefined();
+
+    act(() => {
+      result.current.setScope({ type: "proceedings", id: "p1" });
+    });
+    expect(result.current.scope).toEqual({ type: "proceedings", id: "p1" });
+
+    await act(async () => {
+      await result.current.sendMessage("hello");
+    });
+
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ boundContent: { type: "proceedings", id: "p1" } }));
+
+    // Once a thread exists its scope is fixed.
+    act(() => {
+      result.current.setScope({ type: "proceedings", id: "p2" });
+    });
+    expect(result.current.scope).toEqual({ type: "proceedings", id: "p1" });
+    replaceState.mockRestore();
+  });
+
+  it("the provider scope prop still filters the thread list", async () => {
+    const findMany = vi.fn().mockResolvedValue([]);
+    AssistantService.findMany = findMany;
+
+    const scope = { type: "campaigns", id: "camp-1" };
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider scope={scope}>{children}</AssistantProvider>,
+    });
+
+    await waitFor(() => expect(findMany).toHaveBeenCalledWith({ boundType: "campaigns", boundId: "camp-1" }));
+    expect(result.current.scope).toEqual(scope);
+
+    act(() => {
+      result.current.setScope({ type: "proceedings", id: "p1" });
+    });
+
+    expect(findMany).not.toHaveBeenCalledWith({ boundType: "proceedings", boundId: "p1" });
+    expect(findMany).toHaveBeenLastCalledWith({ boundType: "campaigns", boundId: "camp-1" });
+  });
+
+  it("page heading: thread title as element and a new-thread button that resets the thread", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const existing = buildAssistantDehydrated({ id: "a-h", title: "A thread title longer than 25 chars" });
+    let ctx: ReturnType<typeof useAssistantContext> | undefined;
+    function Probe() {
+      ctx = useAssistantContext();
+      const { title } = useSharedContext();
+      return (
+        <div>
+          <span data-testid="element">{title.element}</span>
+          {title.functions}
+        </div>
+      );
+    }
+    render(
+      <AssistantProvider dehydratedAssistant={existing}>
+        <Probe />
+      </AssistantProvider>,
+    );
+    expect(screen.getByTestId("element")).toHaveTextContent("A thread title longer tha...");
+    fireEvent.click(screen.getByTestId("assistant-new-button"));
+    await waitFor(() => expect(ctx?.assistant).toBeUndefined());
+    expect(screen.getByTestId("element")).toBeEmptyDOMElement();
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants");
+  });
+
+  describe("assistant:created", () => {
+    function fakeSocket() {
+      const handlers: Record<string, (payload: any) => void> = {};
+      const socket = {
+        on: vi.fn((evt: string, h: any) => {
+          handlers[evt] = h;
+        }),
+        off: vi.fn((evt: string) => {
+          delete handlers[evt];
+        }),
+      };
+      vi.mocked(useSocketContext).mockReturnValue({ socket, isConnected: true } as any);
+      return { socket, handlers };
+    }
+
+    function createdEvent(id: string, title: string) {
+      return {
+        assistant: {
+          data: { type: "assistants", id, attributes: { title, messageCount: 0 } },
+          included: [],
+        },
+      };
+    }
+
+    it("names the thread, lists it and swaps the URL before the create request returns", async () => {
+      const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+      const { socket, handlers } = fakeSocket();
+      let resolveCreate!: (value: unknown) => void;
+      AssistantService.create = vi.fn().mockImplementation(() => new Promise((resolve) => (resolveCreate = resolve)));
+      AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([buildMessageStub({ role: "user" })]);
+
+      const { result } = renderHook(() => useAssistantContext(), {
+        wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+      });
+      await waitFor(() => expect(result.current.threadsLoading).toBe(false));
+
+      let sendPromise: Promise<void>;
+      await act(async () => {
+        sendPromise = result.current.sendMessage("first question");
+        await Promise.resolve();
+      });
+      expect(socket.on).toHaveBeenCalledWith("assistant:created", expect.any(Function));
+
+      await act(async () => {
+        handlers["assistant:created"]({ assistant: { data: null } });
+        handlers["assistant:created"](createdEvent("a-new", "Named thread"));
+        handlers["assistant:created"](createdEvent("a-other", "Second event"));
+      });
+
+      expect(result.current.assistant?.id).toBe("a-new");
+      expect(result.current.assistant?.title).toBe("Named thread");
+      expect(result.current.threads.map((t) => t.id)).toEqual(["a-new"]);
+      expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants/a-new");
+      expect(result.current.sending).toBe(true);
+      expect(result.current.messages.map((m) => m.content)).toEqual(["first question"]);
+
+      await act(async () => {
+        resolveCreate(buildAssistantStub({ id: "a-new", title: "Named thread" }));
+        await sendPromise!;
+      });
+
+      expect(result.current.threads.filter((t) => t.id === "a-new")).toHaveLength(1);
+      expect(result.current.threads).toHaveLength(1);
+      expect(result.current.assistant?.id).toBe("a-new");
+      expect(socket.off).toHaveBeenCalledWith("assistant:created", expect.any(Function));
+      replaceState.mockRestore();
+    });
+
+    it("does not touch the URL from the event when manageUrl is false", async () => {
+      const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+      const { handlers } = fakeSocket();
+      let resolveCreate!: (value: unknown) => void;
+      AssistantService.create = vi.fn().mockImplementation(() => new Promise((resolve) => (resolveCreate = resolve)));
+      AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+
+      const { result } = renderHook(() => useAssistantContext(), {
+        wrapper: ({ children }) => <AssistantProvider manageUrl={false}>{children}</AssistantProvider>,
+      });
+      await waitFor(() => expect(result.current.threadsLoading).toBe(false));
+
+      let sendPromise: Promise<void>;
+      await act(async () => {
+        sendPromise = result.current.sendMessage("hello");
+        await Promise.resolve();
+      });
+      await act(async () => {
+        handlers["assistant:created"](createdEvent("a-sheet", "Sheet thread"));
+      });
+
+      expect(result.current.assistant?.id).toBe("a-sheet");
+      expect(result.current.threads.map((t) => t.id)).toEqual(["a-sheet"]);
+      expect(replaceState).not.toHaveBeenCalled();
+
+      await act(async () => {
+        resolveCreate(buildAssistantStub({ id: "a-sheet", title: "Sheet thread" }));
+        await sendPromise!;
+      });
+      expect(replaceState).not.toHaveBeenCalled();
+      replaceState.mockRestore();
+    });
+
+    it("does not subscribe to assistant:created when appending to an existing thread", async () => {
+      const { socket } = fakeSocket();
+      AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+      const { result } = renderHook(() => useAssistantContext(), {
+        wrapper: ({ children }) => (
+          <AssistantProvider dehydratedAssistant={buildAssistantDehydrated({ id: "a-ex" })}>
+            {children}
+          </AssistantProvider>
+        ),
+      });
+      await act(async () => {
+        await result.current.sendMessage("follow-up");
+      });
+      expect(socket.on).not.toHaveBeenCalledWith("assistant:created", expect.any(Function));
+    });
+  });
 });

package/src/features/assistant-action/components/AssistantContainerWithApprovals.tsx

@@ -1,21 +1,43 @@
 "use client";
 
+import type { ReactNode } from "react";
+import type { MentionRenderer } from "../../assistant-message/components/MessageItem";
 import type { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
 import { AssistantContainer } from "../../assistant/components/containers/AssistantContainer";
+import type { AssistantInterface } from "../../assistant/data/AssistantInterface";
 import { useAssistantContext } from "../../assistant/contexts/AssistantContext";
 import { ApprovalActionCard } from "./ApprovalActionCard";
 
+interface Props {
+  renderMention?: MentionRenderer;
+  embedded?: boolean;
+  renderScopePicker?: () => ReactNode;
+  renderThreadBadge?: (thread: AssistantInterface) => ReactNode;
+  showOperatorToggle?: boolean;
+}
+
 /**
  * AssistantContainer with the operator approval card wired in. The container
  * renders `approval-request` messages through the `renderApprovalAction` slot,
  * which stays a slot so the plain chat container has no dependency on the
  * AssistantAction module. Must be rendered inside an `AssistantProvider`.
  */
-export function AssistantContainerWithApprovals() {
+export function AssistantContainerWithApprovals({
+  renderMention,
+  embedded,
+  renderScopePicker,
+  renderThreadBadge,
+  showOperatorToggle,
+}: Props = {}) {
   const ctx = useAssistantContext();
 
   return (
     <AssistantContainer
+      renderMention={renderMention}
+      embedded={embedded}
+      renderScopePicker={renderScopePicker}
+      renderThreadBadge={renderThreadBadge}
+      showOperatorToggle={showOperatorToggle}
       renderApprovalAction={(message: AssistantMessageInterface) =>
         message.actionId ? (
           <ApprovalActionCard

package/src/features/assistant-message/components/EntityMentionLink.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { usePageUrlGenerator } from "../../../hooks";
+import { Link } from "../../../shadcnui";
+import type { MentionRenderer } from "./MessageItem";
+
+function EntityMentionLinkView({ type, id, alias }: { type: string; id: string; alias: string }) {
+  const generate = usePageUrlGenerator();
+
+  let module;
+  try {
+    module = ModuleRegistry.findByName(type);
+  } catch {
+    return <>{alias}</>;
+  }
+  if (!module?.pageUrl) return <>{alias}</>;
+
+  return <Link href={generate({ page: module, id })}>{alias}</Link>;
+}
+
+/**
+ * Default mention renderer for assistant answers: a `mention://<type>/<id>`
+ * link becomes a link to the entity's page when `<type>` is a registered
+ * module with a `pageUrl`, and plain text otherwise. Rendered as a component
+ * so the URL hook runs inside React's component tree.
+ */
+export const EntityMentionLink: MentionRenderer = (p) => <EntityMentionLinkView {...p} />;