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

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";
@@ -224,5 +308,5 @@ The new API provides:
 ## Related
 
 - [Thread Component](/docs/ui/thread) - Main chat interface
-- [Tools Guide](/docs/guides/tools) - Configure assistant actions
+- [Tools Guide](/docs/tools/defining-tools) - Configure assistant actions
 - [Context API](/docs/guides/context-api) - Access assistant state

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/hooks.mdx

@@ -60,6 +60,51 @@ useAuiEvent("thread.runStart", (payload) => {
 });
 ```
 
+### useNotification
+
+Ring the terminal bell and emit an OSC desktop notification when the assistant finishes a run, stops with an error, or pauses for human approval.
+
+```tsx
+import { useNotification } from "@assistant-ui/react-ink";
+
+useNotification();
+```
+
+Defaults:
+
+- `task-complete`: bell + OSC 9
+- `task-incomplete`: bell
+- `needs-input` (assistant message in `requires-action` with `reason: "interrupt"`): bell
+
+Pass `false` to suppress one trigger, or a `NotificationHandler` to override it:
+
+```tsx
+useNotification({
+  onTaskComplete: { osc: "osc99" },
+  onTaskIncomplete: false,
+  onNeedsInput: {
+    custom: (event) => myLogger.log(event),
+  },
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | `boolean` | Master switch. Defaults to `true`. |
+| `onTaskComplete` | `NotificationHandler<"task-complete"> \| false` | Fired when the latest assistant message status flips to `complete` after a run was observed. |
+| `onTaskIncomplete` | `NotificationHandler<"task-incomplete"> \| false` | Fired when the latest assistant message status flips to `incomplete` after a run was observed. |
+| `onNeedsInput` | `NotificationHandler<"needs-input"> \| false` | Fired when the latest assistant message enters `requires-action` with `reason: "interrupt"`. Tool-call pauses are skipped. |
+
+`NotificationHandler<T>` fields (all optional, any combination):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bell` | `boolean` | Ring the terminal bell (`\x07`). |
+| `osc` | `boolean \| "osc9" \| "osc99" \| "osc777"` | Send an OSC notification. `true` is equivalent to `"osc9"`. |
+| `custom` | `(event: Extract<NotificationEvent, { type: T }>) => void` | User callback invoked with the event payload narrowed to this handler's type. |
+
+Notifications are deduplicated per `thread:message:status:reason` tuple, so passing an inline config object does not produce duplicate fires. `ringBell` and `sendOSCNotification(title, body?, variant?)` are also exported for imperative use. OSC support depends on the terminal emulator.
+
 ## Runtime Hooks
 
 ### useLocalRuntime
@@ -108,52 +153,44 @@ const runtime = useRemoteThreadListRuntime({
 
 ## Model Context Hooks
 
-### useAssistantTool
+### Tools
 
-Register a tool with an optional UI renderer. The tool definition is forwarded to the model, and when the model calls it, the `execute` function runs and the `render` component displays the result.
+Register tools with a toolkit. The tool definition is forwarded to the model, and when the model calls it, the `execute` function runs and the `render` component displays the result.
 
-```tsx
-import { useAssistantTool } from "@assistant-ui/react-ink";
+```tsx title="weather-toolkit.tsx"
+import type { Toolkit } from "@assistant-ui/react-ink";
 import { Text } from "ink";
 
-useAssistantTool({
-  toolName: "get_weather",
-  description: "Get the current weather for a city",
-  parameters: {
-    type: "object",
-    properties: {
-      city: { type: "string" },
+export const toolkit = {
+  get_weather: {
+    type: "frontend",
+    description: "Get the current weather for a city",
+    parameters: {
+      type: "object",
+      properties: {
+        city: { type: "string" },
+      },
+      required: ["city"],
     },
-    required: ["city"],
-  },
-  execute: async ({ city }) => {
-    const res = await fetch(`https://api.weather.example/${city}`);
-    return res.json();
+    execute: async ({ city }) => {
+      const res = await fetch(`https://api.weather.example/${city}`);
+      return res.json();
+    },
+    render: ({ args, result }) => (
+      <Text>{args.city}: {result?.temperature}°F</Text>
+    ),
   },
-  render: ({ args, result }) => (
-    <Text>{args.city}: {result?.temperature}°F</Text>
-  ),
-});
+} satisfies Toolkit;
 ```
 
-### useAssistantToolUI
-
-Register only a UI renderer for a tool (without tool definition or execute function).
-
-```tsx
-import { useAssistantToolUI } from "@assistant-ui/react-ink";
-import { Text } from "ink";
+```tsx title="ToolProvider.tsx"
+import { AuiProvider, Tools, useAui } from "@assistant-ui/react-ink";
+import { toolkit } from "./weather-toolkit";
 
-useAssistantToolUI({
-  toolName: "get_weather",
-  render: ({ args, result, status }) => (
-    <Text>
-      {status?.type === "running"
-        ? `Loading weather for ${args.city}...`
-        : `${args.city}: ${result?.temperature}°F`}
-    </Text>
-  ),
-});
+function ToolProvider({ children }: { children: React.ReactNode }) {
+  const aui = useAui({ tools: Tools({ toolkit }) });
+  return <AuiProvider value={aui}>{children}</AuiProvider>;
+}
 ```
 
 ### useAssistantInstructions
@@ -181,48 +218,9 @@ useAssistantDataUI({
   ),
 });
 ```
-### makeAssistantTool
-
-Create a component that registers a tool when mounted.
-
-```tsx
-import { makeAssistantTool } from "@assistant-ui/react-ink";
-import { Text } from "ink";
-
-const WeatherTool = makeAssistantTool({
-  toolName: "get_weather",
-  description: "Get weather",
-  parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
-  execute: async ({ city }) => ({ temperature: 72 }),
-  render: ({ args, result }) => <Text>{args.city}: {result?.temperature}°F</Text>,
-});
-
-// Mount inside AssistantRuntimeProvider to register
-<WeatherTool />
-```
-
-### makeAssistantToolUI
+### Dynamic Tool Renderers
 
-Create a component that registers only a tool UI renderer (no tool definition or execute) when mounted.
-
-```tsx
-import { makeAssistantToolUI } from "@assistant-ui/react-ink";
-import { Text } from "ink";
-
-const WeatherToolUI = makeAssistantToolUI({
-  toolName: "get_weather",
-  render: ({ args, result, status }) => (
-    <Text>
-      {status?.type === "running"
-        ? `Loading weather for ${args.city}...`
-        : `${args.city}: ${result?.temperature}°F`}
-    </Text>
-  ),
-});
-
-// Mount inside AssistantRuntimeProvider to register
-<WeatherToolUI />
-```
+Use a toolkit with `useInlineRender` when the renderer closes over changing props.
 
 ### makeAssistantDataUI
 
@@ -247,16 +245,31 @@ const WeatherCardUI = makeAssistantDataUI({
 
 Wrap a render function component so that it always uses the latest version without re-creating a stable reference. Useful when passing a render prop inline and the function closes over changing state.
 
-```tsx
-import { useInlineRender } from "@assistant-ui/react-ink";
-
-const render = useInlineRender(({ args, result }) => (
-  <Text>{args.city}: {result?.temperature}°F</Text>
-));
+```tsx title="weather-toolkit.tsx"
+import { type Toolkit, useInlineRender } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+import { useMemo } from "react";
 
-useAssistantToolUI({ toolName: "get_weather", render });
+export function useWeatherToolkit() {
+  const render = useInlineRender(({ args, result }) => (
+    <Text>{args.city}: {result?.temperature}°F</Text>
+  ));
+
+  return useMemo(
+    () =>
+      ({
+        get_weather: {
+          type: "backend",
+          render,
+        },
+      }) satisfies Toolkit,
+    [render],
+  );
+}
 ```
 
+Import the toolkit hook, pass its result to `useAui({ tools: Tools({ toolkit }) })`, and provide the returned `aui` with `AuiProvider`, as shown in the [Tools](#tools) section above.
+
 ## Runtime Providers
 
 ### AssistantRuntimeProvider

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 (

package/.docs/raw/docs/ink/migration.mdx

@@ -9,7 +9,7 @@ If you already have an assistant-ui web app, most of your code transfers directl
 
 - **Runtime setup** — `useLocalRuntime`, `ChatModelAdapter`, and all runtime options work identically.
 - **AI SDK integration** — `@assistant-ui/react-ai-sdk` works with React Ink. Your runtime setup transfers directly.
-- **Tool definitions** — `useAssistantTool`, `makeAssistantTool`, and tool UI renderers use the same API.
+- **Tool definitions** — `Tools({ toolkit })` and toolkit renderers use the same API.
 - **State hooks** — `useAuiState`, `useAui`, and selector patterns are the same.
 - **Backend code** — Your API routes, streaming endpoints, and server-side logic need zero changes.