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

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

@@ -0,0 +1,292 @@
+---
+title: Interactables
+description: Persistent UI whose state can be read and updated by the AI assistant.
+---
+
+import { InteractableSample } from "@/components/docs/samples/interactable";
+
+Interactables are React components that live outside the chat message flow and have state that both the user and the AI can read and write. This enables AI-driven UI patterns where the assistant controls parts of your application beyond the chat window.
+
+<InteractableSample />
+
+## Overview
+
+Unlike regular tool UIs that appear inline within messages, interactables:
+
+- **Persist across messages** — they live outside the chat thread
+- **Have shared state** — both the user (via React) and the AI (via auto-generated tools) can update them
+- **Support partial updates** — the AI only needs to send the fields it wants to change
+- **Are developer-placed** — you decide where they render in your app
+- **Auto-register tools** — the AI automatically gets a tool to update each interactable's state
+
+Common use cases:
+
+- Task boards that the AI can add items to
+- Data dashboards that update based on conversation
+- Forms that the AI pre-fills
+- Canvas/editor components that the AI can manipulate
+
+## Quick Start
+
+### 1. Register the Interactables scope
+
+```tsx
+import { useAui, Interactables, AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
+  const runtime = useChatRuntime();
+
+  const aui = useAui({
+    interactables: Interactables(),
+  });
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+### 2. Create an interactable
+
+<Callout type="warn">
+  Define the `stateSchema` and `initialState` **outside** the component (or
+  memoize them). Creating a new schema on every render will cause the
+  interactable to re-register and reset its state.
+</Callout>
+
+```tsx
+import { useInteractable } from "@assistant-ui/react";
+import { z } from "zod";
+
+const taskBoardSchema = z.object({
+  tasks: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      done: z.boolean(),
+    }),
+  ),
+});
+
+const taskBoardInitialState = { tasks: [] };
+
+function TaskBoard() {
+  const [state, setState] = useInteractable("taskBoard", {
+    description: "A task board showing the user's tasks",
+    stateSchema: taskBoardSchema,
+    initialState: taskBoardInitialState,
+  });
+
+  return (
+    <div>
+      <h2>Tasks</h2>
+      <ul>
+        {state.tasks.map((task) => (
+          <li key={task.id}>
+            <label>
+              <input
+                type="checkbox"
+                checked={task.done}
+                onChange={() =>
+                  setState((prev) => ({
+                    tasks: prev.tasks.map((t) =>
+                      t.id === task.id ? { ...t, done: !t.done } : t,
+                    ),
+                  }))
+                }
+              />
+              {task.title}
+            </label>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### 3. Place it in your layout
+
+```tsx
+function App() {
+  return (
+    <MyRuntimeProvider>
+      <div className="flex">
+        <Thread className="flex-1" />
+        <TaskBoard /> {/* Lives outside the chat */}
+      </div>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+Now when the user says _"Add a task called 'Buy groceries'"_, the AI will automatically call the `update_taskBoard` tool to update the state. Thanks to partial updates, the AI only needs to send the fields it wants to change.
+
+## Partial Updates
+
+Auto-generated tools use a partial schema — all fields become optional. The AI only sends the fields it wants to change; omitted fields keep their current values.
+
+```tsx
+// If the state is { title: "My Note", content: "Hello", color: "yellow" }
+// The AI can call: update_note({ color: "blue" })
+// Result: { title: "My Note", content: "Hello", color: "blue" }
+```
+
+This is especially useful for large state objects where regenerating the entire state would be expensive and error-prone.
+
+<Callout type="info">
+  Merge is shallow (one level deep). If the AI sends a nested object, it replaces
+  that entire field rather than deep-merging into it.
+</Callout>
+
+## Multiple Instances
+
+You can render multiple interactables with the same `name` but different `id`s. Each gets its own update tool:
+
+```tsx
+import { useInteractable } from "@assistant-ui/react";
+import { z } from "zod";
+
+const noteSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  color: z.enum(["yellow", "blue", "green", "pink"]),
+});
+
+const noteInitialState = { title: "New Note", content: "", color: "yellow" as const };
+
+function NoteCard({ noteId }: { noteId: string }) {
+  const [state] = useInteractable("note", {
+    id: noteId,
+    description: "A sticky note",
+    stateSchema: noteSchema,
+    initialState: noteInitialState,
+  });
+
+  return <div>{state.title}</div>;
+}
+
+function App() {
+  return (
+    <>
+      <NoteCard noteId="note-1" /> {/* → update_note_note-1 tool */}
+      <NoteCard noteId="note-2" /> {/* → update_note_note-2 tool */}
+    </>
+  );
+}
+```
+
+When only one instance of a name exists, the tool is named `update_{name}` (e.g., `update_note`). When multiple instances exist, tools are named `update_{name}_{id}` (e.g., `update_note_note-1`).
+
+## Selection
+
+When multiple interactables are present, you can mark one as "selected" to tell the AI which one the user is focused on:
+
+```tsx
+function NoteCard({ noteId }: { noteId: string }) {
+  const [state, setState, { setSelected }] = useInteractable("note", {
+    id: noteId,
+    description: "A sticky note",
+    stateSchema: noteSchema,
+    initialState: noteInitialState,
+  });
+
+  return (
+    <div onClick={() => setSelected(true)}>
+      {state.title}
+    </div>
+  );
+}
+```
+
+The AI sees `(SELECTED)` in the system prompt for the focused interactable, allowing it to prioritize that one in responses. For example, the user can say _"Change the color to blue"_ and the AI knows which note to update.
+
+## API Reference
+
+### `useInteractable`
+
+Hook that registers an interactable and returns its state with a setter.
+
+```tsx
+const [state, setState, meta] = useInteractable<TState>(name, config);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Name for the interactable (used in tool names) |
+| `config.description` | `string` | Description shown to the AI |
+| `config.stateSchema` | `StandardSchemaV1 \| JSONSchema7` | Schema for the state (e.g., a Zod schema) |
+| `config.initialState` | `TState` | Initial state value |
+| `config.id` | `string?` | Optional unique instance ID (auto-generated if omitted) |
+| `config.selected` | `boolean?` | Whether this interactable is selected |
+
+**Returns:** `[state, setState, { id, setSelected }]`
+
+| Return | Type | Description |
+| --- | --- | --- |
+| `state` | `TState` | Current state |
+| `setState` | `(updater: TState \| (prev: TState) => TState) => void` | State setter (like `useState`) |
+| `meta.id` | `string` | The instance ID (auto-generated or provided) |
+| `meta.setSelected` | `(selected: boolean) => void` | Mark this interactable as selected |
+
+### `makeInteractable`
+
+Declarative API that creates a component which registers an interactable when mounted. Useful for static configurations.
+
+```tsx
+import { makeInteractable } from "@assistant-ui/react";
+
+const TaskBoardInteractable = makeInteractable({
+  name: "taskBoard",
+  description: "A task board showing the user's tasks",
+  stateSchema: taskBoardSchema,
+  initialState: taskBoardInitialState,
+});
+
+// Mount it anywhere — renders nothing, just registers the interactable
+function App() {
+  return (
+    <>
+      <TaskBoardInteractable />
+      <Thread />
+    </>
+  );
+}
+```
+
+### `Interactables`
+
+The scope resource that manages all interactables. Register it via `useAui`:
+
+```tsx
+const aui = useAui({
+  interactables: Interactables(),
+});
+```
+
+## How It Works
+
+When you call `useInteractable("taskBoard", config)`:
+
+1. **Registration** — the interactable is registered in the `interactables` scope with its name, description, schema, and initial state.
+2. **Tool generation** — an `update_taskBoard` frontend tool is automatically created with a partial schema (all fields optional). For multiple instances, tools are named `update_{name}_{id}`.
+3. **System prompt** — the AI receives a system message describing the interactable, its current state, and whether it is selected.
+4. **Streaming updates** — as the AI generates the tool arguments, the interactable's state updates progressively rather than waiting for complete arguments. This gives users immediate visual feedback.
+5. **Partial merge** — only the fields the AI sends are updated; the rest are preserved.
+6. **Bidirectional updates** — when the AI calls the tool, the state updates and React re-renders. When the user updates state via `setState`, the model context is notified so the AI sees the latest state on the next turn.
+
+## Combining with Tools
+
+You can use `Interactables` alongside `Tools`:
+
+```tsx
+const aui = useAui({
+  tools: Tools({ toolkit: myToolkit }),
+  interactables: Interactables(),
+});
+```

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 />
@@ -57,8 +58,8 @@ const AssistantMessage: FC = () => {
 | `streamStartTime` | `number` | Unix timestamp when stream started |
 | `firstTokenTime` | `number?` | Time to first text token (ms) |
 | `totalStreamTime` | `number?` | Total stream duration (ms) |
-| `tokenCount` | `number?` | Real or estimated output token count |
-| `tokensPerSecond` | `number?` | Throughput (tokens/sec); see [accuracy note](#ai-sdk-usechatruntime) |
+| `tokenCount` | `number?` | Output token count from message metadata usage |
+| `tokensPerSecond` | `number?` | Throughput (tokens/sec), when token usage is available |
 | `totalChunks` | `number` | Total stream chunks received |
 | `toolCallCount` | `number` | Number of tool calls |
 
@@ -89,7 +90,7 @@ const runtime = useDataStreamRuntime({ api: "/api/chat" });
 Timing is tracked automatically on the client side by observing streaming state transitions and content changes. Timing is finalized when each stream completes.
 
 <Callout type="warn">
-  `tokenCount` and `tokensPerSecond` are **estimated** using a 4 characters per token approximation — real token counts from the server are not extracted. This can overcount significantly for short messages.
+  `tokenCount` and `tokensPerSecond` require usage metadata from `finish` or `finish-step` in your AI SDK route. If usage metadata is not emitted, duration and TTFT metrics still work, but token-based metrics are omitted.
 </Callout>
 
 ```tsx

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

@@ -0,0 +1,174 @@
+---
+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
+- [Sub-Agent Model Tracking](/docs/cloud/ai-sdk#sub-agent-model-tracking) — Track delegated model usage and costs in the Cloud dashboard