@assistant-ui/mcp-docs-server 0.1.31 → 0.1.32

package/.docs/raw/docs/guides/suggestions.mdx

@@ -1,6 +1,6 @@
 ---
-title: Suggestions
-description: Display suggested prompts to help users get started with your assistant.
+title: Suggested Prompts
+description: Display suggested starter prompts in your AI chat to onboard users faster. Configurable suggestion components for React, built into assistant-ui.
 platforms: ["react"]
 ---
 
@@ -136,9 +136,93 @@ Suggestions dismiss automatically once the user sends a message because `thread.
 
 The primitives available for rendering suggestions are `ThreadPrimitive.Suggestions`, `ThreadPrimitive.SuggestionByIndex`, `SuggestionPrimitive.Title`, `SuggestionPrimitive.Description`, and `SuggestionPrimitive.Trigger`. `ThreadPrimitive.SuggestionByIndex` is useful when you need layout control over a specific suggestion slot rather than iterating all of them. For the full prop reference and usage patterns, see the [Suggestion primitive docs](/docs/primitives/suggestion).
 
-## Dynamic Suggestions
+## Runtime driven suggestions
 
-You can dynamically change suggestions based on your application state:
+The static `Suggestions(...)` API covers welcome screens. For follow up prompts that depend on the conversation, a tool result, or your backend, push suggestions through the runtime itself. They land on `thread.suggestions` rather than the static `suggestions` scope, so they render through a different component.
+
+### Local runtime: `SuggestionAdapter`
+
+Pass a `suggestion` adapter to `useLocalRuntime`. Its `generate` function runs after every assistant turn and may return a promise or an async generator for streaming updates.
+
+```tsx
+import { useLocalRuntime, type SuggestionAdapter } from "@assistant-ui/react";
+
+const suggestionAdapter: SuggestionAdapter = {
+  async generate({ messages }) {
+    const response = await fetch("/api/follow-ups", {
+      method: "POST",
+      body: JSON.stringify({ messages }),
+    });
+    const data: { prompt: string }[] = await response.json();
+    return data;
+  },
+};
+
+const runtime = useLocalRuntime(myChatModel, {
+  adapters: { suggestion: suggestionAdapter },
+});
+```
+
+### External store runtime
+
+`useExternalStoreRuntime` exposes a `suggestions` field, so you can drive follow ups straight from your application state.
+
+```tsx
+const [suggestions, setSuggestions] = useState<ThreadSuggestion[]>([]);
+
+const runtime = useExternalStoreRuntime({
+  messages,
+  onNew,
+  suggestions,
+});
+
+// Push a follow up after a tool result, a stream chunk, or any app event.
+setSuggestions([{ prompt: "Summarize this case" }]);
+```
+
+### AI SDK runtime
+
+`useChatRuntime` and `useAISDKRuntime` accept the same `suggestions` field and forward it to the underlying external store.
+
+```tsx
+const [suggestions, setSuggestions] = useState<ThreadSuggestion[]>([]);
+
+const runtime = useChatRuntime({ suggestions });
+```
+
+The local runtime clears its suggestions when a new run starts. External store and AI SDK runtimes keep whatever state you push, so you control the lifetime.
+
+### Rendering runtime suggestions
+
+Static suggestions go through `ThreadPrimitive.Suggestions`; runtime suggestions go through `thread.suggestions`. The shadcn registry ships `ThreadFollowupSuggestions` for the common single line pill layout. For a custom layout, read the array yourself:
+
+```tsx
+import { useAuiState, ThreadPrimitive, AuiIf } from "@assistant-ui/react";
+
+function FollowUps() {
+  const suggestions = useAuiState((s) => s.thread.suggestions);
+  return (
+    <AuiIf condition={(s) => !s.thread.isEmpty && !s.thread.isRunning}>
+      <div className="flex gap-2">
+        {suggestions.map((s, i) => (
+          <ThreadPrimitive.Suggestion
+            key={i}
+            prompt={s.prompt}
+            method="replace"
+            autoSend
+          >
+            {s.prompt}
+          </ThreadPrimitive.Suggestion>
+        ))}
+      </div>
+    </AuiIf>
+  );
+}
+```
+
+## Reacting to application state
+
+You can dynamically change the static suggestion list based on your application state:
 
 ```tsx
 import { useMemo } from "react";

package/.docs/raw/docs/guides/tool-ui.mdx

@@ -1,6 +1,6 @@
 ---
 title: Generative UI
-description: Render tool calls as interactive UI instead of plain text.
+description: Render AI tool calls as interactive React components — charts, forms, maps, and custom widgets. Build generative UI patterns in chat with assistant-ui.
 platforms: ["react"]
 ---
 
@@ -200,7 +200,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-4o"),
+    model: openai("gpt-5.4-nano"),
     messages: await convertToModelMessages(messages),
     tools: {
       getWeather: tool({

package/.docs/raw/docs/guides/tools.mdx

@@ -1,6 +1,6 @@
 ---
-title: Tools
-description: Give your assistant actions like API calls, database queries, and more.
+title: Tool Calling
+description: Add API calls, database queries, and custom actions to your AI chat with assistant-ui's tool calling. Real-time visualization, type safety, and streaming.
 platforms: ["react"]
 ---
 
@@ -100,6 +100,7 @@ type ToolDefinition =
       description?: string;
       parameters: StandardSchemaV1 | JSONSchema7; // e.g. a Zod schema
       execute: (args, context) => Promise<any>;
+      toModelOutput?: (opts) => ToolModelContentPart[]; // see "Multi-modal tool results"
       render?: (props) => React.ReactNode;
     }
   | {
@@ -116,6 +117,66 @@ type ToolDefinition =
     };
 ```
 
+### Multi-modal Tool Results
+
+By default, the value returned from `execute` is sent to the model as a single JSON blob. That is fine for most tools, but it does not work for tools whose useful output is a file or image: a "read PDF" tool, an OCR tool, a chart-rendering tool, etc.
+
+`toModelOutput` is an optional callback that maps the developer-facing `execute` result into the multi-modal content the model actually sees. Your `render` function still receives the rich, typed `result`; the model receives the projection.
+
+```tsx
+import { tool } from "@assistant-ui/react";
+import { convertUint8ArrayToBase64 } from "@ai-sdk/provider-utils";
+import { z } from "zod";
+
+const readPdfTool = tool({
+  description: "Fetch a PDF from a URL and return it",
+  parameters: z.object({ url: z.string().url() }),
+  execute: async ({ url }) => {
+    const res = await fetch(url);
+    const buf = new Uint8Array(await res.arrayBuffer());
+    const base64 = convertUint8ArrayToBase64(buf);
+    return { mediaType: "application/pdf", base64, byteLength: buf.byteLength };
+  },
+  toModelOutput: ({ output }) => [
+    { type: "text", text: "PDF contents:" },
+    {
+      type: "file",
+      data: output.base64,
+      mediaType: output.mediaType,
+    },
+  ],
+});
+```
+
+`ToolModelContentPart` is a union of `{ type: "text"; text }` and `{ type: "file"; data; mediaType; filename? }`. Use `mediaType` (e.g. `image/png`, `application/pdf`) to tell the model how to interpret the bytes.
+
+When using the AI SDK runtime, frontend tool results round-trip through the AI SDK chat protocol back to your route handler on the next turn. For `toModelOutput` to fire on those round-tripped results, your route handler must also pass the tool registry to `convertToModelMessages`. This is the [same pattern AI SDK documents](https://ai-sdk.dev/docs/reference/ai-sdk-ui/convert-to-model-messages#multi-modal-tool-responses) for any multi-modal tool response:
+
+```ts
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import { convertToModelMessages, streamText } from "ai";
+
+const aiSDKTools = { ...frontendTools(tools ?? {}) };
+
+const result = streamText({
+  model,
+  // Pass tools to both calls. convertToModelMessages reads `toModelOutput`
+  // from `tools[toolName]` to project prior tool results.
+  messages: await convertToModelMessages(messages, { tools: aiSDKTools }),
+  tools: aiSDKTools,
+});
+```
+
+If you skip the `{ tools: aiSDKTools }` argument, prior tool results will be sent to the model as a plain JSON blob (the AI SDK default), and your `toModelOutput` will be silently ignored. Tools that do not declare `toModelOutput` are unaffected either way.
+
+<Callout type="warn">
+  **Reserved property name.** When `toModelOutput` is set, the runtime wraps the AI SDK chat output as `{ __aui_modelContent: ToolModelContentPart[], value: <your result> }` before persisting. Do not return objects whose top-level key is literally `__aui_modelContent` from any tool's `execute`, or it will be misread as the envelope. The prefix is namespaced for this reason; any other property name is fine.
+</Callout>
+
+<Callout type="warn">
+  **Read/write compatibility for persisted threads.** The `__aui_modelContent` envelope is recognized by `@assistant-ui/react-ai-sdk` from this version onward. If you persist UI messages (thread history adapter, cloud, etc.) and read them from multiple environments, upgrade every reader before any writer starts producing `toModelOutput`. Older readers will treat the entire envelope as the `result`, which breaks tool `render` functions for those messages.
+</Callout>
+
 ### Organizing Large Toolkits
 
 For larger applications, split tools across multiple files:
@@ -464,7 +525,7 @@ import { z } from "zod";
 export async function POST(req: Request) {
   const { messages } = await req.json();
   const result = streamText({
-    model: openai("gpt-4o"),
+    model: openai("gpt-5.4-nano"),
     messages: await convertToModelMessages(messages),
     tools: {
       queryDatabase: tool({
@@ -519,7 +580,7 @@ export async function POST(req: Request) {
   const { messages, tools } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-4o"),
+    model: openai("gpt-5.4-nano"),
     messages: await convertToModelMessages(messages),
     tools: {
       ...frontendTools(tools), // Client-defined tools
@@ -558,7 +619,7 @@ export async function POST(req: Request) {
     const tools = await client.tools();
 
     const result = streamText({
-      model: openai("gpt-4o"),
+      model: openai("gpt-5.4-nano"),
       tools,
       messages: await convertToModelMessages(messages),
     });

package/.docs/raw/docs/guides/voice.mdx

@@ -1,6 +1,6 @@
 ---
-title: Realtime Voice
-description: Bidirectional realtime voice conversations with AI agents.
+title: Realtime Voice Chat
+description: Build bidirectional voice conversations with AI in React — realtime audio streaming, interruption handling, and visual state, integrated via assistant-ui.
 platforms: ["react"]
 ---
 

package/.docs/raw/docs/ink/adapters.mdx

@@ -1,10 +1,46 @@
 ---
 title: Adapters
-description: Title generation adapters for React Ink.
+description: Title generation and storage adapters for React Ink.
 ---
 
 Adapters customize runtime behavior. They can be passed as options to `useLocalRuntime` or `useRemoteThreadListRuntime`.
 
+## createFileStorageAdapter
+
+A `RemoteThreadListAdapter` that persists threads and messages to a local directory. See [Custom Backend → Option 2](/docs/ink/custom-backend#option-2-local-file-persistence) for usage.
+
+```ts
+import { createFileStorageAdapter } from "@assistant-ui/react-ink";
+
+const adapter = createFileStorageAdapter({
+  dir: "/path/to/threads",
+});
+```
+
+## TitleGenerationAdapter
+
+Produces a thread title from a thread's messages. Pass one as the `titleGenerator` option to `createFileStorageAdapter`, or call it from a custom `RemoteThreadListAdapter`.
+
+```ts
+type TitleGenerationAdapter = {
+  generateTitle(messages: readonly ThreadMessage[]): Promise<string>;
+};
+```
+
+`createSimpleTitleAdapter` is the built-in implementation; it derives the title from the first user message, truncated to 50 characters.
+
+```ts
+import {
+  createFileStorageAdapter,
+  createSimpleTitleAdapter,
+} from "@assistant-ui/react-ink";
+
+const adapter = createFileStorageAdapter({
+  dir: "/path/to/threads",
+  titleGenerator: createSimpleTitleAdapter(),
+});
+```
+
 ## RemoteThreadListAdapter
 
 Title generation is configured via the `generateTitle` method on `RemoteThreadListAdapter`. See the [Custom Backend](/docs/ink/custom-backend) page for a full example.

package/.docs/raw/docs/ink/custom-backend.mdx

@@ -59,7 +59,57 @@ This gives you:
 - In-memory thread list (lost on process exit)
 - Multi-thread support
 
-## Option 2: Full backend thread management
+## Option 2: Local file persistence
+
+When you want threads and messages to survive across sessions without running a backend, use `createFileStorageAdapter`. It writes each thread to a JSON file on disk and plugs into `useRemoteThreadListRuntime`.
+
+```tsx title="app.tsx"
+import { join } from "node:path";
+import { homedir } from "node:os";
+import {
+  useLocalRuntime,
+  useRemoteThreadListRuntime,
+  createFileStorageAdapter,
+  AssistantRuntimeProvider,
+} from "@assistant-ui/react-ink";
+import { myChatAdapter } from "./adapters/my-chat-adapter.js";
+
+const threadListAdapter = createFileStorageAdapter({
+  dir: join(homedir(), ".my-cli", "threads"),
+});
+
+function useAppRuntime() {
+  return useRemoteThreadListRuntime({
+    runtimeHook: () => useLocalRuntime(myChatAdapter),
+    adapter: threadListAdapter,
+  });
+}
+
+export function App() {
+  const runtime = useAppRuntime();
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {/* your chat UI */}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+Writes are atomic (temp file + `rename`), so a crash mid-write cannot leave a partial JSON file. The directory is created lazily on first write.
+
+### Options
+
+| Option | Description |
+|---|---|
+| `dir` | Directory where thread files are stored. Created if missing. |
+| `prefix` | Key prefix for stored files. Defaults to `@assistant-ui:`. Useful when two apps share a directory. |
+| `titleGenerator` | Optional [`TitleGenerationAdapter`](/docs/ink/adapters#titlegenerationadapter) that auto-generates thread titles from the first messages. Pass `createSimpleTitleAdapter()` for the built-in implementation. |
+
+### When this fits
+
+Designed for single-process terminal apps where one user has one CLI running at a time. The wrapped read-modify-write on the thread list isn't lock-safe, so two CLI processes pointed at the same directory can lose updates to thread metadata (rename, archive). If that's your scenario, use Option 3 instead.
+
+## Option 3: Full backend thread management
 
 When you want your backend to own thread state (e.g. for persistence across sessions, team sharing, or server-side history), implement a `RemoteThreadListAdapter`.
 
@@ -194,10 +244,11 @@ export function App() {
 
 ## Which option to choose?
 
-| | Option 1: ChatModelAdapter | Option 2: RemoteThreadListAdapter |
-|---|---|---|
-| **Thread storage** | In-memory (process lifetime) | Your backend |
-| **Message storage** | In-memory | On-device (can add history adapter for server-side) |
-| **Cross-session persistence** | No | Yes |
-| **Setup complexity** | Minimal | Moderate |
-| **Best for** | CLI tools, demos, prototypes | Production apps with persistence |
+| | Option 1: ChatModelAdapter | Option 2: createFileStorageAdapter | Option 3: RemoteThreadListAdapter |
+|---|---|---|---|
+| **Thread storage** | In-memory (process lifetime) | Local disk | Your backend |
+| **Message storage** | In-memory | Local disk | In-memory (can add history adapter for server-side) |
+| **Cross-session persistence** | No | Yes | Yes |
+| **Multi-process safe** | N/A | No | Depends on backend |
+| **Setup complexity** | Minimal | Minimal | Moderate |
+| **Best for** | Demos, prototypes | Local CLI tools | Production apps with sync / team sharing |

package/.docs/raw/docs/ink/index.mdx

@@ -1,6 +1,6 @@
 ---
-title: Getting Started
-description: Build AI chat interfaces for the terminal with @assistant-ui/react-ink.
+title: Terminal AI Chat with Ink
+description: Build AI chat interfaces for the terminal in TypeScript with @assistant-ui/react-ink — streaming, tool calls, and keyboard navigation in CLI apps.
 ---
 
 ## Quick Start
@@ -129,6 +129,7 @@ import { Box, Text } from "ink";
 import {
   ThreadPrimitive,
   ComposerPrimitive,
+  LoadingPrimitive,
   useAuiState,
 } from "@assistant-ui/react-ink";
 import { MarkdownText } from "@assistant-ui/react-ink-markdown";
@@ -158,15 +159,13 @@ const Message = () => {
   );
 };
 
-const StatusIndicator = () => {
-  const isRunning = useAuiState((s) => s.thread.isRunning);
-  if (!isRunning) return null;
-  return (
-    <Box marginBottom={1}>
-      <Text color="yellow">Thinking...</Text>
-    </Box>
-  );
-};
+const StatusIndicator = () => (
+  <LoadingPrimitive.Root marginBottom={1} gap={1}>
+    <LoadingPrimitive.Spinner variant="bar" />
+    <LoadingPrimitive.Text />
+    <LoadingPrimitive.ElapsedTime />
+  </LoadingPrimitive.Root>
+);
 
 export const Thread = () => {
   return (