@assistant-ui/mcp-docs-server 0.1.24 → 0.1.25

package/.docs/raw/docs/(docs)/guides/context-api.mdx

@@ -30,13 +30,18 @@ assistant-ui organizes state into **scopes** - logical boundaries that provide a
     └── 💬 Thread (thread) - Active conversation with messages
         ├── 🔵 Message (message) - User or assistant message
         │   ├── 📝 Part (part) - Content within a message (text, tool calls, etc.)
+        │   ├── 🧠 ChainOfThought (chainOfThought) - Reasoning steps within a message
+        │   │   └── 📝 Part (part) - Individual reasoning/tool-call step
         │   ├── 📎 Attachment (attachment) - Files attached to messages
         │   └── ✏️  Composer (composer) - Edit mode for existing messages
         │       └── 📎 Attachment (attachment) - Files in edit mode
         └── ✏️  Composer (composer) - New message input
             └── 📎 Attachment (attachment) - Files being added
 
+💡 Suggestions (suggestions) - Follow-up message suggestions
+    └── 💬 Suggestion (suggestion) - Individual suggestion item
 🔧 Tools (tools) - Custom UI components for tool calls
+🧩 ModelContext (modelContext) - Model context and tool registration
 ```
 
 **How scopes work:**
@@ -166,12 +171,12 @@ The API object is stable and doesn't cause re-renders. Use it for:
 // Thread actions
 aui.thread().append(message);
 aui.thread().startRun(config);
+aui.thread().resumeRun(config);
 aui.thread().cancelRun();
-aui.thread().switchToNewThread();
-aui.thread().switchToThread(threadId);
 aui.thread().getState();
-aui.thread().message(idOrIndex);
-aui.thread().composer;
+aui.thread().message({ index: idx });
+aui.thread().message({ id: messageId });
+aui.thread().composer();
 
 // Message actions
 aui.message().reload();
@@ -180,12 +185,14 @@ aui.message().stopSpeaking();
 aui.message().submitFeedback({ type: "positive" | "negative" });
 aui.message().switchToBranch({ position, branchId });
 aui.message().getState();
-aui.message().part(indexOrToolCallId);
-aui.message().composer;
+aui.message().part({ index: idx });
+aui.message().part({ toolCallId });
+aui.message().composer();
 
 // Part actions
-api.part().addResult(result);
-api.part().getState();
+aui.part().addToolResult(result);
+aui.part().resumeToolCall(result);
+aui.part().getState();
 
 // Composer actions
 aui.composer().send();
@@ -193,8 +200,8 @@ aui.composer().setText(text);
 aui.composer().setRole(role);
 aui.composer().addAttachment(file); // File object
 aui.composer().addAttachment({ name, content }); // external source
-aui.composer().clearAttachments();
-aui.composer().reset();
+await aui.composer().clearAttachments();
+await aui.composer().reset();
 aui.composer().getState();
 
 // Attachment actions
@@ -212,7 +219,23 @@ aui.threadListItem().rename(title);
 aui.threadListItem().archive();
 aui.threadListItem().unarchive();
 aui.threadListItem().delete();
-aui.threads().getState();
+aui.threadListItem().getState();
+
+// Suggestions actions
+aui.suggestions().getState();
+aui.suggestions().suggestion({ index: 0 });
+
+// Suggestion actions
+aui.suggestion().getState();
+
+// ChainOfThought actions
+aui.chainOfThought().getState();
+aui.chainOfThought().setCollapsed(collapsed);
+aui.chainOfThought().part({ index: 0 });
+
+// ModelContext actions
+aui.modelContext().getState();
+aui.modelContext().register(provider);
 
 // Tools actions
 aui.tools().setToolUI(toolName, render);
@@ -228,26 +251,29 @@ import { useAuiEvent } from "@assistant-ui/react";
 
 // Listen to current scope events (most common)
 useAuiEvent("composer.send", (event) => {
-  console.log("Current composer sent message:", event.message);
+  console.log("Composer sent message in thread:", event.threadId);
+});
+
+// Listen to thread events
+useAuiEvent("thread.runStart", (event) => {
+  console.log("Run started in thread:", event.threadId);
 });
 
 // Listen to all events of a type across all scopes
 useAuiEvent({ event: "composer.send", scope: "*" }, (event) => {
-  console.log("Any composer sent a message:", event);
+  console.log("Any composer sent a message:", event.threadId);
 });
 
 // Listen to ALL events (useful for debugging or analytics)
 useAuiEvent("*", (event) => {
-  console.log("Event occurred:", event.type, "from:", event.source);
-  // Send to analytics, logging, etc.
+  console.log("Event occurred:", event.event, event.payload);
 });
 
 // Practical example: Track user interactions
 function AnalyticsTracker() {
   useAuiEvent("composer.send", (event) => {
     analytics.track("message_sent", {
-      messageLength: event.message.content.length,
-      hasAttachments: event.message.attachments.length > 0,
+      threadId: event.threadId,
     });
   });
 
@@ -272,9 +298,13 @@ Each scope provides access to specific state and actions:
 - **Thread** (`thread`): Conversation with messages
 - **Message** (`message`): Individual message (user or assistant)
 - **Part** (`part`): Content part within a message (text, tool calls, etc.)
+- **ChainOfThought** (`chainOfThought`): Reasoning steps grouped within a message
 - **Composer** (`composer`): Text input for sending or editing messages
 - **Attachment** (`attachment`): File or media attached to a message or composer
+- **Suggestions** (`suggestions`): Collection of follow-up message suggestions
+- **Suggestion** (`suggestion`): Individual follow-up suggestion
 - **Tools** (`tools`): Tool UI components
+- **ModelContext** (`modelContext`): Model context and tool registration
 
 ### Scope Resolution
 
@@ -301,7 +331,7 @@ Before accessing a scope, check if it's available:
 const aui = useAui();
 
 // Check if message scope exists
-if (api.message.source) {
+if (aui.message.source) {
   // Safe to use message scope
   const { role } = aui.message().getState();
 }
@@ -325,9 +355,9 @@ const partByToolCall = aui.message().part({ toolCallId: "call_123" });
 // Access attachment by index
 const attachment = aui.composer().attachment({ index: 0 }).getState();
 
-// Access thread from thread list
-const thread = aui.threads().thread("main");
+// Access thread list item by ID or index
 const threadItem = aui.threads().item({ id: "thread_123" });
+const threadByIndex = aui.threads().item({ index: 0 });
 ```
 
 ## Common Patterns
@@ -400,7 +430,7 @@ function MessageCounter() {
 
 ### Resolution Dynamics
 
-When you call `api.scope()`, the API resolves the current scope at that moment. This resolution happens each time you call the function, which matters when dealing with changing contexts:
+When you call `aui.scope()`, the API resolves the current scope at that moment. This resolution happens each time you call the function, which matters when dealing with changing contexts:
 
 ```tsx
 const aui = useAui();
@@ -458,27 +488,35 @@ const isRunning = useAuiState((s) => s.thread.isRunning);
 
 ### Scope States
 
-| Scope          | Key State Properties                                                              | Description                                      |
-| -------------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
-| ThreadList     | `mainThreadId`, `threadIds`, `isLoading`, `threadItems`                           | Manages all available conversation threads       |
-| ThreadListItem | `id`, `title`, `status`, `remoteId`, `externalId`                                 | Individual thread metadata and status            |
-| Thread         | `isRunning`, `isLoading`, `isDisabled`, `messages`, `capabilities`, `suggestions` | Active conversation state and message history    |
-| Message        | `role`, `content`, `status`, `attachments`, `parentId`, `branchNumber`, `isLast`  | Individual message content and metadata          |
-| Composer       | `text`, `role`, `attachments`, `isEmpty`, `canCancel`, `type`, `isEditing`        | Text input state for new/edited messages         |
-| Part           | `type`, `content`, `status`, `text`, `toolCallId`, `toolName`                     | Content parts within messages (text, tool calls) |
-| Attachment     | `id`, `type`, `name`, `url`, `size`, `mimeType`                                   | File attachments metadata and content            |
+| Scope          | Key State Properties                                                                             | Description                                        |
+| -------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| ThreadList     | `mainThreadId`, `newThreadId`, `threadIds`, `archivedThreadIds`, `isLoading`, `threadItems`     | Manages all available conversation threads         |
+| ThreadListItem | `id`, `title`, `status`, `remoteId`, `externalId`                                               | Individual thread metadata and status              |
+| Thread         | `isRunning`, `isLoading`, `isDisabled`, `isEmpty`, `messages`, `capabilities`, `suggestions`    | Active conversation state and message history      |
+| Message        | `role`, `content`, `status`, `attachments`, `parts`, `parentId`, `branchNumber`, `branchCount`, `isLast`, `index` | Individual message content and metadata |
+| Part           | `type`, `status`, `text`, `toolCallId`, `toolName`                                              | Content parts within messages (text, tool calls)   |
+| ChainOfThought | `parts`, `collapsed`, `status`                                                                   | Reasoning steps grouped within a message           |
+| Composer       | `text`, `role`, `attachments`, `isEmpty`, `canCancel`, `type`, `isEditing`                      | Text input state for new/edited messages           |
+| Attachment     | `id`, `type`, `name`, `contentType`, `status`                                                   | File attachments metadata and content              |
+| Suggestions    | `suggestions`                                                                                    | Collection of follow-up message suggestions        |
+| Suggestion     | `title`, `label`, `prompt`                                                                       | Individual suggestion with title, label, and prompt |
+| ModelContext   | *(empty — use `register()` / `getToolCallParams()` methods)*                                     | Model context and tool registration                |
 
 ### Available Actions by Scope
 
-| Scope          | Actions                                                                   | Use Cases                                 |
-| -------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
-| ThreadList     | `switchToNewThread()`, `switchToThread(id)`, `getState()`                 | Thread navigation and creation            |
-| ThreadListItem | `switchTo()`, `rename(title)`, `archive()`, `unarchive()`, `delete()`     | Thread management operations              |
-| Thread         | `append(message)`, `startRun()`, `cancelRun()`, `switchToNewThread()`     | Message handling and conversation control |
-| Message        | `reload()`, `speak()`, `stopSpeaking()`, `submitFeedback(feedback)`       | Message interactions and regeneration     |
-| Composer       | `send()`, `setText(text)`, `addAttachment(file \| attachment)`, `reset()` | Text input and message composition        |
-| Part           | `addResult(result)`, `getState()`                                         | Tool call result handling                 |
-| Attachment     | `remove()`, `getState()`                                                  | File management                           |
+| Scope          | Actions                                                                                                           | Use Cases                                  |
+| -------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| ThreadList     | `switchToNewThread()`, `switchToThread(id)`, `item(selector)`, `thread("main")`, `getState()`                    | Thread navigation and creation             |
+| ThreadListItem | `switchTo()`, `rename(title)`, `archive()`, `unarchive()`, `delete()`, `getState()`                              | Thread management operations               |
+| Thread         | `append(message)`, `startRun(config)`, `resumeRun(config)`, `cancelRun()`, `reset()`, `export()`, `import(repository)`, `message(selector)`, `composer()`, `getState()` | Message handling and conversation control |
+| Message        | `reload()`, `speak()`, `stopSpeaking()`, `submitFeedback(feedback)`, `switchToBranch(options)`, `getCopyText()`, `part(selector)`, `attachment(selector)`, `composer()`, `setIsCopied(value)`, `setIsHovering(value)`, `getState()` | Message interactions and regeneration |
+| Part           | `addToolResult(result)`, `resumeToolCall(result)`, `getState()`                                                   | Tool call result handling                  |
+| ChainOfThought | `setCollapsed(collapsed)`, `part({ index })`, `getState()`                                                        | Expand/collapse reasoning steps            |
+| Composer       | `send()`, `setText(text)`, `setRole(role)`, `addAttachment(file \| attachment)`, `clearAttachments()` (async), `reset()` (async), `getState()` | Text input and message composition |
+| Attachment     | `remove()`, `getState()`                                                                                          | File management                            |
+| Suggestions    | `suggestion({ index })`, `getState()`                                                                             | Access follow-up suggestions               |
+| Suggestion     | `getState()`                                                                                                      | Read individual suggestion data            |
+| ModelContext   | `register(provider)`, `getState()`                                                                                | Register model context providers           |
 
 ### Common Events
 
@@ -508,7 +546,7 @@ function SafeMessageButton() {
   const aui = useAui();
 
   const role = useAuiState((s) =>
-    api.message.source !== undefined ? s.message.role : "none",
+    aui.message.source !== undefined ? s.message.role : "none",
   );
 
   return <div>Role: {role}</div>;
@@ -558,18 +596,18 @@ const value = useAuiState((s) => s.scope.property);
 
 // Perform action
 const aui = useAui();
-api.scope().action();
+aui.scope().action();
 
 // Listen to events
 useAuiEvent("source.event", (e) => {});
 
 // Check scope availability
-if (api.scope.source) {
+if (aui.scope.source) {
   /* scope exists */
 }
 
 // Get state imperatively
-const state = api.scope().getState();
+const state = aui.scope().getState();
 
 // Navigate scopes
 aui.thread().message({ id: "..." }).getState();

package/.docs/raw/docs/(docs)/guides/dictation.mdx

@@ -38,7 +38,7 @@ const runtime = useChatRuntime({
 The dictation feature uses `ComposerPrimitive.Dictate` and `ComposerPrimitive.StopDictation` components.
 
 ```tsx
-import { ComposerPrimitive } from "@assistant-ui/react";
+import { AuiIf, ComposerPrimitive } from "@assistant-ui/react";
 import { MicIcon, SquareIcon } from "lucide-react";
 
 const ComposerWithDictation = () => (
@@ -46,18 +46,18 @@ const ComposerWithDictation = () => (
     <ComposerPrimitive.Input />
 
     {/* Show Dictate button when not dictating */}
-    <ComposerPrimitive.If dictation={false}>
+    <AuiIf condition={(s) => s.composer.dictation == null}>
       <ComposerPrimitive.Dictate>
         <MicIcon />
       </ComposerPrimitive.Dictate>
-    </ComposerPrimitive.If>
+    </AuiIf>
 
     {/* Show Stop button when dictating */}
-    <ComposerPrimitive.If dictation>
+    <AuiIf condition={(s) => s.composer.dictation != null}>
       <ComposerPrimitive.StopDictation>
         <SquareIcon className="animate-pulse" />
       </ComposerPrimitive.StopDictation>
-    </ComposerPrimitive.If>
+    </AuiIf>
 
     <ComposerPrimitive.Send />
   </ComposerPrimitive.Root>

package/.docs/raw/docs/(docs)/guides/editing.mdx

@@ -9,8 +9,8 @@ Give the user the ability to edit their message.
 
 You can show an editor interface by using `ComposerPrimitive`.
 
-```tsx {1,11,25,31-43}
-import { ComposerPrimitive } from "@assistant-ui/react";
+```tsx {1-2,11,25,31-52}
+import { ComposerPrimitive, useAuiState } from "@assistant-ui/react";
 ...
 
 const Thread = () => {
@@ -18,10 +18,12 @@ const Thread = () => {
     <ThreadPrimitive.Root>
       <ThreadPrimitive.Viewport>
         ...
-        <ThreadPrimitive.Messages components={{
-          ...,
-          EditComposer, // <-- Show our new component during edit mode
-        }} />
+        <ThreadPrimitive.Messages>
+          {({ message }) => {
+            // Show our new component during edit mode
+            return <MessageWithEditComposer />;
+          }}
+        </ThreadPrimitive.Messages>
       </ThreadPrimitive.Viewport>
       ...
     </ThreadPrimitive.Root>
@@ -40,7 +42,14 @@ const UserMessage = () => {
   );
 };
 
-// define a new component
+// define a wrapper component that handles both display and edit mode
+const MessageWithEditComposer = () => {
+  const isEditing = useAuiState((s) => s.composer.isEditing);
+  if (isEditing) return <EditComposer />;
+  return <UserMessage />;
+};
+
+// define the edit composer component
 const EditComposer = () => {
   return (
     // you can return a MessagePrimitive including a ComposerPrimitive, or only a ComposerPrimitive

package/.docs/raw/docs/(docs)/guides/latex.mdx

@@ -32,6 +32,7 @@ import "katex/dist/katex.min.css"; // [!code ++]
 ### Update `markdown-text.tsx`
 
 ```tsx title="/components/assistant-ui/markdown-text.tsx"
+import { MarkdownTextPrimitive } from "@assistant-ui/react-markdown";
 import remarkMath from "remark-math";     // [!code ++]
 import rehypeKatex from "rehype-katex";   // [!code ++]
 
@@ -69,6 +70,8 @@ Many language models generate LaTeX using different delimiter formats:
 You can use the `preprocess` prop to normalize these formats:
 
 ```tsx title="/components/assistant-ui/markdown-text.tsx"
+import { MarkdownTextPrimitive } from "@assistant-ui/react-markdown";
+
 const MarkdownTextImpl = () => {
   return (
     <MarkdownTextPrimitive

package/.docs/raw/docs/(docs)/guides/message-timing.mdx

@@ -14,6 +14,7 @@ Display stream performance metrics — duration, tokens per second, TTFT — on
 Use `useMessageTiming()` inside a message component to access timing data:
 
 ```tsx
+import type { FC } from "react";
 import { useMessageTiming } from "@assistant-ui/react";
 
 const MessageTimingDisplay: FC = () => {
@@ -39,7 +40,7 @@ Place it inside `MessagePrimitive.Root`, typically near the action bar:
 const AssistantMessage: FC = () => {
   return (
     <MessagePrimitive.Root>
-      <MessagePrimitive.Parts components={{ ... }} />
+      <MessagePrimitive.Parts>{...}</MessagePrimitive.Parts>
       <ActionBarPrimitive.Root>
         <ActionBarPrimitive.Copy />
         <ActionBarPrimitive.Reload />

package/.docs/raw/docs/(docs)/guides/multi-agent.mdx

@@ -0,0 +1,173 @@
+---
+title: Multi-Agent
+description: Render sub-agent conversations inside tool call UIs.
+---
+
+In a multi-agent (orchestrator) architecture, a main agent invokes sub-agents via tool calls. Each sub-agent may produce its own conversation (user/assistant messages, tool calls, etc.). assistant-ui supports rendering these nested conversations using the `MessagePartPrimitive.Messages` primitive.
+
+## Overview
+
+When a tool call includes a `messages` field (`ToolCallMessagePart.messages`), it represents a sub-agent's conversation history. `MessagePartPrimitive.Messages` reads this field from the current tool call part and renders it as a nested thread.
+
+Key behaviors:
+
+- **Scope inheritance** — Parent tool UI registrations are available in sub-agent messages. A `makeAssistantToolUI` registered at the top level works inside sub-agent conversations too.
+- **Recursive** — Sub-agent messages can contain tool calls that themselves have nested messages. Just use `MessagePartPrimitive.Messages` again.
+- **Read-only** — Sub-agent messages are rendered in a readonly context. No editing, branching, or composing.
+
+## Quick Start
+
+<Steps>
+  <Step>
+
+### Register a Tool UI for the Sub-Agent
+
+```tsx
+import {
+  makeAssistantToolUI,
+  MessagePartPrimitive,
+} from "@assistant-ui/react";
+
+const ResearchAgentToolUI = makeAssistantToolUI({
+  toolName: "invoke_researcher",
+  render: ({ args, status }) => (
+    <div className="my-2 rounded-lg border p-4">
+      <div className="mb-2 text-sm font-medium text-gray-500">
+        Researcher Agent {status.type === "running" && "(working...)"}
+      </div>
+      <MessagePartPrimitive.Messages>
+        {({ message }) => {
+          if (message.role === "user") return <MyUserMessage />;
+          return <MyAssistantMessage />;
+        }}
+      </MessagePartPrimitive.Messages>
+    </div>
+  ),
+});
+```
+
+  </Step>
+  <Step>
+
+### Provide the Messages from the Backend
+
+Your backend must populate the `messages` field on the tool call result. For example, with the AI SDK:
+
+```ts title="api/chat/route.ts"
+tools: {
+  invoke_researcher: tool({
+    description: "Invoke the researcher sub-agent",
+    parameters: z.object({ query: z.string() }),
+    execute: async ({ query }) => {
+      const subAgentMessages = await runResearcherAgent(query);
+      return {
+        answer: subAgentMessages.at(-1)?.content,
+        // The messages field is picked up by assistant-ui
+        messages: subAgentMessages,
+      };
+    },
+  }),
+},
+```
+
+<Callout type="info">
+  The exact mechanism for populating `messages` depends on your backend
+  framework. The key requirement is that the tool result's corresponding
+  `ToolCallMessagePart` includes a `messages` array of `ThreadMessage` objects.
+</Callout>
+
+  </Step>
+  <Step>
+
+### Register the Tool UI Component
+
+```tsx
+function App() {
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+      <ResearchAgentToolUI />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+  </Step>
+</Steps>
+
+## Recursive Sub-Agents
+
+If a sub-agent's tool calls also have nested messages, the same pattern applies recursively:
+
+```tsx
+const OuterAgentToolUI = makeAssistantToolUI({
+  toolName: "invoke_planner",
+  render: () => (
+    <div className="rounded border p-3">
+      <h4>Planner Agent</h4>
+      <MessagePartPrimitive.Messages>
+        {({ message }) => {
+          if (message.role === "user") return <MyUserMessage />;
+          return (
+            <MessagePrimitive.Parts>
+              {({ part }) => {
+                if (part.type === "text") return <MyText />;
+                if (part.type === "tool-call" && part.toolName === "invoke_researcher") return (
+                  <div className="ml-4 rounded border p-3">
+                    <h5>Researcher Agent</h5>
+                    {/* Nested sub-agent renders recursively */}
+                    <MessagePartPrimitive.Messages>
+                      {({ message }) => {
+                        if (message.role === "user") return <MyUserMessage />;
+                        return <MyAssistantMessage />;
+                      }}
+                    </MessagePartPrimitive.Messages>
+                  </div>
+                );
+                if (part.type === "tool-call") return <MyToolFallback {...part} />;
+                return null;
+              }}
+            </MessagePrimitive.Parts>
+          );
+        }}
+      </MessagePartPrimitive.Messages>
+    </div>
+  ),
+});
+```
+
+## ReadonlyThreadProvider
+
+For advanced use cases where you have a `ThreadMessage[]` array and want to render it as a thread outside of a tool call context, use `ReadonlyThreadProvider` directly:
+
+```tsx
+import {
+  ReadonlyThreadProvider,
+  ThreadPrimitive,
+  type ThreadMessage,
+} from "@assistant-ui/react";
+
+function SubConversation({
+  messages,
+}: {
+  messages: readonly ThreadMessage[];
+}) {
+  return (
+    <ReadonlyThreadProvider messages={messages}>
+      <ThreadPrimitive.Messages>
+        {({ message }) => {
+          if (message.role === "user") return <MyUserMessage />;
+          return <MyAssistantMessage />;
+        }}
+      </ThreadPrimitive.Messages>
+    </ReadonlyThreadProvider>
+  );
+}
+```
+
+`ReadonlyThreadProvider` inherits the parent's tool UI registrations and model context through scope inheritance.
+
+## Related
+
+- [Generative UI](/docs/guides/tool-ui) — Creating tool call UIs
+- [MessagePartPrimitive](/docs/api-reference/primitives/message-part) — API reference for message part primitives