@assistant-ui/mcp-docs-server 0.1.39 → 0.2.1

package/.docs/raw/docs/guides/electron.mdx

@@ -0,0 +1,369 @@
+---
+title: Electron
+description: Run assistant-ui in an Electron renderer with a hosted backend or a secure, streaming preload and IPC bridge.
+platforms: ["react"]
+---
+
+assistant-ui works in Electron through `@assistant-ui/react`. The renderer is a React DOM environment, so there is no separate `@assistant-ui/electron` package to install. The Electron-specific decision is where model requests run and how the renderer reaches them.
+
+<Callout type="warn">
+  Never put a provider API key in renderer code, a `VITE_*` variable, or a preload script. Bundled values are readable by anyone with the app. Keep remote credentials on your backend, or keep local credentials in the main process and provision them with an OS-backed secret store.
+</Callout>
+
+## Choose a connection pattern
+
+| Pattern | Use it when | Runtime |
+| --- | --- | --- |
+| Hosted backend | You already have an AI SDK endpoint, need server auth or persistence, or ship the app to other people | `useChatRuntime` with an absolute HTTPS URL |
+| Local main process | The desktop app owns the provider or agent process and must work without your web backend | `useLocalRuntime` with a narrow preload/IPC bridge |
+
+```mermaid
+flowchart LR
+  Renderer["Electron renderer<br/>assistant-ui React"] -->|"absolute HTTPS"| Backend["Hosted chat backend"]
+  Renderer -->|"window.assistantAI"| Preload["context-isolated preload"]
+  Preload -->|"transferred MessagePort"| Main["Electron main process"]
+  Backend --> Provider["Model or agent"]
+  Main --> Provider
+```
+
+Do not send an SDK client, assistant-ui runtime, callback, `AbortSignal`, or `File` through IPC. Electron IPC uses structured clone semantics; define a small data-only protocol instead.
+
+## Pattern 1: hosted backend
+
+This is the smallest integration. Keep your existing AI SDK chat route and point `AssistantChatTransport` at its public URL.
+
+```tsx title="renderer/assistant-runtime.tsx"
+import type { ReactNode } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  AssistantChatTransport,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+
+const transport = new AssistantChatTransport({
+  api: "https://api.example.com/chat",
+});
+
+export function ElectronRuntimeProvider({ children }: { children: ReactNode }) {
+  const runtime = useChatRuntime({ transport });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+The URL must be absolute in a packaged app. A relative value such as `/api/chat` targets the renderer's `file://` or custom-protocol origin, not your deployed backend. Configure the backend's CORS policy for the packaged origin, allow the endpoint in `connect-src`, and authenticate requests as you would from any desktop client.
+
+The endpoint must return the AI SDK UI message stream consumed by `AssistantChatTransport`. See the [AI SDK runtime guide](/docs/runtimes/ai-sdk/v7) for the backend route and tool-calling setup.
+
+## Pattern 2: local main process
+
+Use this pattern when the Electron main process calls the model or runs a local agent. Keep `contextIsolation: true`, `sandbox: true`, and `nodeIntegration: false` on the `BrowserWindow`. Register `registerAssistantIpc(mainWindow)` after creating the trusted window.
+
+The following example is intentionally text-only. It streams one request over a dedicated `MessagePort`; closing that port propagates assistant-ui's Stop action to an `AbortController` in the main process.
+
+### 1. Define a data-only protocol
+
+Place the shared types somewhere all three Electron bundles can import.
+
+```ts title="shared/assistant-ipc.ts"
+export const ASSISTANT_STREAM_CHANNEL = "assistant:stream";
+
+export type ChatMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string };
+
+export type ChatRequest = {
+  system?: string;
+  messages: ChatMessage[];
+};
+
+export type ChatEvent =
+  | { type: "delta"; text: string }
+  | { type: "done" }
+  | { type: "error"; message: string };
+
+export type AssistantAI = {
+  streamChat(
+    request: ChatRequest,
+    onEvent: (event: ChatEvent) => void,
+  ): () => void;
+};
+```
+
+### 2. Expose one preload capability
+
+Expose the smallest API the renderer needs, not `ipcRenderer` itself. The callback receives only validated event data, never Electron's privileged IPC event object.
+
+```ts title="preload/assistant.ts"
+import { contextBridge, ipcRenderer } from "electron";
+import {
+  ASSISTANT_STREAM_CHANNEL,
+  type AssistantAI,
+  type ChatEvent,
+} from "./shared";
+
+const assistantAI: AssistantAI = {
+  streamChat(request, onEvent) {
+    const { port1, port2 } = new MessageChannel();
+    const onMessage = (event: MessageEvent<ChatEvent>) => onEvent(event.data);
+
+    port1.addEventListener("message", onMessage);
+    port1.start();
+    ipcRenderer.postMessage(ASSISTANT_STREAM_CHANNEL, request, [port2]);
+
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      port1.removeEventListener("message", onMessage);
+      port1.close();
+    };
+  },
+};
+
+contextBridge.exposeInMainWorld("assistantAI", assistantAI);
+```
+
+Declare the context-bridge API for renderer TypeScript:
+
+```ts title="renderer/electron.d.ts"
+import type { AssistantAI } from "./shared";
+
+declare global {
+  interface Window {
+    assistantAI: AssistantAI;
+  }
+}
+
+export {};
+```
+
+### 3. Stream from the main process
+
+Install the provider packages in the Electron main-process bundle:
+
+```sh
+pnpm add ai @ai-sdk/openai
+```
+
+The handler checks both the sending `WebContents` and its main frame, validates the untrusted payload and bounds its size before calling the model. Set `OPENAI_API_KEY` only in the main-process environment.
+
+```ts title="main/assistant-ipc.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+import { ipcMain, type BrowserWindow, type IpcMainEvent } from "electron";
+import {
+  ASSISTANT_STREAM_CHANNEL,
+  type ChatEvent,
+  type ChatRequest,
+} from "./shared";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isChatRequest = (value: unknown): value is ChatRequest => {
+  if (!isRecord(value) || !Array.isArray(value.messages)) return false;
+  if (value.system !== undefined && typeof value.system !== "string") {
+    return false;
+  }
+  if (value.messages.length > 200) return false;
+
+  let totalLength = typeof value.system === "string" ? value.system.length : 0;
+  for (const message of value.messages) {
+    if (!isRecord(message)) return false;
+    if (message.role !== "user" && message.role !== "assistant") return false;
+    if (typeof message.content !== "string") return false;
+    totalLength += message.content.length;
+    if (totalLength > 1_000_000) return false;
+  }
+
+  return true;
+};
+
+export function registerAssistantIpc(mainWindow: BrowserWindow) {
+  const handleStream = (event: IpcMainEvent, request: unknown) => {
+    const [port] = event.ports;
+    if (!port) return;
+
+    if (
+      event.sender !== mainWindow.webContents ||
+      event.senderFrame !== mainWindow.webContents.mainFrame
+    ) {
+      port.close();
+      return;
+    }
+
+    port.start();
+    if (!isChatRequest(request)) {
+      port.postMessage({
+        type: "error",
+        message: "Invalid chat request.",
+      } satisfies ChatEvent);
+      port.close();
+      return;
+    }
+
+    const abortController = new AbortController();
+    port.once("close", () => abortController.abort());
+    const send = (message: ChatEvent) => port.postMessage(message);
+
+    void (async () => {
+      try {
+        const result = streamText({
+          model: openai("gpt-5.6-luna"),
+          messages: request.messages,
+          ...(request.system ? { system: request.system } : {}),
+          abortSignal: abortController.signal,
+        });
+
+        for await (const text of result.textStream) {
+          send({ type: "delta", text });
+        }
+        send({ type: "done" });
+      } catch (error) {
+        if (abortController.signal.aborted) return;
+        console.error("Assistant stream failed", error);
+        send({ type: "error", message: "The model request failed." });
+      }
+    })();
+  };
+
+  ipcMain.on(ASSISTANT_STREAM_CHANNEL, handleStream);
+  mainWindow.once("closed", () => {
+    ipcMain.removeListener(ASSISTANT_STREAM_CHANNEL, handleStream);
+  });
+}
+```
+
+If your app can open more than one trusted assistant window, register a unique channel per window or route requests through one application-level registry. A global `ipcMain.on` listener should not be re-registered under the same channel for every window.
+
+### 4. Adapt IPC to assistant-ui
+
+`ChatModelAdapter` yields complete snapshots, so the renderer accumulates each IPC delta before yielding it. Its cleanup function closes the port on Stop, unmount, or completion.
+
+```tsx title="renderer/assistant-runtime.tsx"
+import type { ReactNode } from "react";
+import {
+  AssistantRuntimeProvider,
+  useLocalRuntime,
+  type ChatModelAdapter,
+} from "@assistant-ui/react";
+import type { ChatMessage } from "./shared";
+
+const ipcChatModel: ChatModelAdapter = {
+  async *run({ messages, context, abortSignal }) {
+    abortSignal.throwIfAborted();
+
+    const system = [context.system];
+    const serializedMessages: ChatMessage[] = [];
+
+    for (const message of messages) {
+      const text = message.content
+        .flatMap((part) => (part.type === "text" ? [part.text] : []))
+        .join("\n");
+      if (!text) continue;
+
+      if (message.role === "system") system.push(text);
+      if (message.role === "user") {
+        serializedMessages.push({ role: "user", content: text });
+      }
+      if (message.role === "assistant") {
+        serializedMessages.push({ role: "assistant", content: text });
+      }
+    }
+
+    const systemText = system.filter(Boolean).join("\n\n");
+    let stop: (() => void) | undefined;
+    let removeAbortListener: (() => void) | undefined;
+    const deltas = new ReadableStream<string>({
+      start(controller) {
+        let settled = false;
+        const close = () => {
+          if (settled) return;
+          settled = true;
+          controller.close();
+        };
+        const fail = (error: unknown) => {
+          if (settled) return;
+          settled = true;
+          controller.error(error);
+        };
+
+        stop = window.assistantAI.streamChat(
+          {
+            ...(systemText ? { system: systemText } : {}),
+            messages: serializedMessages,
+          },
+          (event) => {
+            if (event.type === "delta") controller.enqueue(event.text);
+            if (event.type === "done") close();
+            if (event.type === "error") fail(new Error(event.message));
+          },
+        );
+
+        const onAbort = () => {
+          stop?.();
+          fail(abortSignal.reason);
+        };
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+        removeAbortListener = () =>
+          abortSignal.removeEventListener("abort", onAbort);
+        if (abortSignal.aborted) onAbort();
+      },
+      cancel() {
+        stop?.();
+      },
+    });
+
+    const reader = deltas.getReader();
+    let fullText = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        fullText += value;
+        yield { content: [{ type: "text", text: fullText }] };
+      }
+    } finally {
+      removeAbortListener?.();
+      stop?.();
+      reader.releaseLock();
+    }
+  },
+};
+
+export function ElectronRuntimeProvider({ children }: { children: ReactNode }) {
+  const runtime = useLocalRuntime(ipcChatModel);
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+Wrap your existing assistant-ui thread with `ElectronRuntimeProvider`. Primitives and installed UI components work exactly as they do in a browser React app.
+
+## Extend the protocol deliberately
+
+The local example drops every non-text content part. Add explicit structured-clone-safe fields before claiming support for more features:
+
+- Attachments: pass bounded `ArrayBuffer` data or an app-owned file reference after validating type, size, and path in the main process. Do not pass browser `File` objects.
+- Tools: define serializable tool-call and tool-result events, and validate every tool invocation in the privileged process. Never expose a generic shell or filesystem IPC method.
+- Reasoning and metadata: add distinct event variants and map them to the corresponding assistant-ui content parts.
+- Thread persistence: store serializable thread data in the main process or use a remote thread-list adapter; do not try to transfer a runtime object.
+
+## Packaged-app checklist
+
+- Use an absolute HTTPS endpoint, a privileged custom protocol, or the preload bridge. Relative `/api/*` routes that worked against a development server will not follow your backend after packaging.
+- Serve local content through a custom protocol instead of `file://` when possible, and define a restrictive Content Security Policy. Do not disable `webSecurity` to work around origin errors.
+- Validate every IPC sender and every payload in the main process. Treat renderer data as untrusted even when the renderer is local.
+- Intercept new windows and external links with `webContents.setWindowOpenHandler`; do not let model-generated links create unrestricted Electron windows.
+- If you render remote HTML with `SafeContentFrame`, allow its documented host in `frame-src`. Ordinary text and Markdown rendering need no Electron-specific change.
+- Test the packaged build, not only the Vite or Webpack development server. The scheme, origin, preload path, CSP, and environment loading can all differ.
+
+For the underlying platform constraints, see Electron's official guides to [IPC and MessagePorts](https://www.electronjs.org/docs/latest/tutorial/message-ports), [context isolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation), and the [security checklist](https://www.electronjs.org/docs/latest/tutorial/security).

package/.docs/raw/docs/guides/index.mdx

@@ -105,3 +105,13 @@ Alternative ways to connect a model.
     Run your app locally on a ChatGPT Plus or Pro plan via Codex OAuth, no API key required.
   </Card>
 </Cards>
+
+## Environments
+
+Run assistant-ui outside a conventional browser deployment.
+
+<Cards>
+  <Card title="Electron" href="/docs/guides/electron">
+    Connect an Electron renderer to a hosted backend or a secure, streaming preload/IPC bridge.
+  </Card>
+</Cards>

package/.docs/raw/docs/guides/quoting.mdx

@@ -127,7 +127,7 @@ function CustomQuoteDisplay() {
 
 ## Programmatic API
 
-Set or clear quotes via `useAui` from `@assistant-ui/react`. Call `aui.thread().composer().setQuote()` when your component is rendered outside of a specific thread context, or `aui.composer().setQuote()` when it is rendered inside a thread:
+Set or clear quotes via `useAui` from `@assistant-ui/react`. Call `aui.thread.composer().setQuote()` when your component is rendered outside of a specific thread context, or `aui.composer.setQuote()` when it is rendered inside a thread:
 
 ```tsx
 import { useAui } from "@assistant-ui/react";
@@ -136,14 +136,14 @@ function MyComponent() {
   const aui = useAui();
 
   const quoteText = () => {
-    aui.thread().composer().setQuote({
+    aui.thread.composer().setQuote({
       text: "The text to quote",
       messageId: "msg-123",
     });
   };
 
   const clearQuote = () => {
-    aui.thread().composer().setQuote(undefined);
+    aui.thread.composer().setQuote(undefined);
   };
 
   return (

package/.docs/raw/docs/guides/resumable-stream-deployment.mdx

@@ -143,7 +143,7 @@ Per-tenant prefixes also make incident response cheaper. A `SCAN MATCH aui:app:t
 
 ## Observability hooks
 
-`ResumableStreamContextOptions` exposes lifecycle hooks for structured logging, metrics, and tracing. Each hook is invoked synchronously around the underlying store call; throwing inside a hook surfaces as a producer error.
+`ResumableStreamContextOptions` exposes lifecycle hooks for structured logging, metrics, and tracing. Hook exceptions and rejected promises are reported through `console.error` without affecting stream output or stored lifecycle status.
 
 ```ts title="/lib/resumable-context.ts"
 import { createResumableStreamContext } from "assistant-stream/resumable";
@@ -170,7 +170,7 @@ export const resumableContext = createResumableStreamContext({
 });
 ```
 
-Keep hook bodies cheap. They run on the producer's hot path and any latency they add becomes streaming latency seen by the client.
+Keep synchronous hook work cheap. `onAcquire` runs on the `run()` request path for producers and consumers alike, while the remaining hooks run on the producer's streaming hot path. Returned promises are observed for failures but are not awaited.
 
 ## Resource limits
 

package/.docs/raw/docs/guides/resumable-streams.mdx

@@ -84,7 +84,7 @@ The context exposes two more verbs: `ctx.status(streamId)` returns `"streaming"
 
 ## Client side: native integration
 
-`@assistant-ui/react-ai-sdk` ships a `resumable` option on `AssistantChatTransport`. It captures the stream id from the response header, redirects `chat.resumeStream()` reconnects to your resume route, and clears the stored id when the response finishes naturally. Pair it with `useChatRuntime`, which fires `chat.resumeStream()` on mount whenever a pending id is present in storage.
+`@assistant-ui/react-ai-sdk` ships a `resumable` option on `AssistantChatTransport`. It captures the stream id from the response header, redirects `chat.resumeStream()` reconnects to your resume route, and clears the stored id when the response finishes naturally. Pair it with `useChatRuntime`, which fires `chat.resumeStream()` whenever its resumable storage reports a pending id, including ids discovered after mount.
 
 ```tsx title="/app/page.tsx"
 "use client";
@@ -127,12 +127,83 @@ export default function Page() {
 }
 ```
 
-`onResumeError` runs when the client finds a stored stream id but the reconnect attempt fails. Use it to show a toast, report telemetry, or mark the thread as needing retry; assistant-ui still clears the stale stream id after the callback runs.
+`onResumeError` runs when the client finds a stored stream id but the reconnect attempt fails. Use it to show a toast, report telemetry, or mark the thread as needing retry. Assistant-ui clears the failed stream id after the callback unless a newer id has replaced it.
 
-`createResumableSessionStorage` returns a `ResumableClientStorage` backed by `window.sessionStorage`. Pass `{ key }` to namespace per route or per chat surface, or supply your own implementation of the three methods (`getStreamId`, `setStreamId`, `clear`). If you are running on a transport that already wraps `fetch` or `prepareReconnectToStreamRequest`, the `resumable` option composes with your existing handlers.
+`createResumableSessionStorage` returns a `ResumableClientStorage` backed by `window.sessionStorage`. Pass `{ key }` to namespace per route or chat surface; `key` also accepts a getter that is read lazily on every access, so you can derive it from the active thread's identity (see [Multiple threads](#multiple-threads)). While the getter returns `undefined`, reads report no pending stream and writes are dropped. Reuse one storage instance per key, because separate instances do not synchronize their in-memory caches. The persisted entry survives reloads, while in-memory ownership prevents one mounted thread from attaching to another thread's pending stream. An idle follower that learns a stream id from its backend can call `storage.setStreamId(streamId, threadId)` after the corresponding message exists in local history; the runtime attaches when that thread is current, without requiring a remount. The built-in storage holds one pending stream id per key; the [Multiple threads](#multiple-threads) pattern gives each thread its own key, so several threads stay resumable at once. A custom `ResumableClientStorage` can instead key its records by the optional `threadId` arguments and implement `subscribe(listener, threadId)` for post-mount updates, or replace the storage methods entirely. If you are running on a transport that already wraps `fetch` or `prepareReconnectToStreamRequest`, the `resumable` option composes with your existing handlers.
 
 The default finish detector scans the SSE body for the AI SDK `"type":"finish"` marker. Override `isFinishEvent` on the `resumable` option when you ship a custom encoder.
 
+### Multiple threads
+
+The snippet above stores the pending stream id under one `sessionStorage` key, which is correct for a single chat surface. Under a thread list runtime (`useRemoteThreadListRuntime`, which `useChatRuntime` wraps) with more than one alive thread, a single shared key is written and cleared by whichever thread acts last: switch threads while a response is in flight and the response header writes its stream id to the shared key, which the thread you switched to reads on mount and resumes — replaying the other conversation's stream into this one. An unscoped clear when a stream finishes can also drop another thread's pending id. And after a reload, a pending id under the shared key is claimed by whichever thread is main at mount, which with a thread list is a fresh empty thread rather than the one that started the stream.
+
+Scope the key to the thread, and construct the transport and storage per thread inside the per-thread runtime hook rather than once at module level. Derive the key from the thread's identity with a getter so it is read lazily on every access:
+
+```tsx title="/app/page.tsx"
+"use client";
+
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+  useAui,
+  useCloudThreadListAdapter,
+  useRemoteThreadListRuntime,
+} from "@assistant-ui/react";
+import {
+  AssistantChatTransport,
+  createResumableSessionStorage,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+import { useMemo } from "react";
+import { Thread } from "@/components/assistant-ui/thread";
+import { ThreadList } from "@/components/assistant-ui/thread-list";
+
+const cloud = new AssistantCloud({
+  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+  anonymous: true,
+});
+
+function ResumableThreadRuntime() {
+  const aui = useAui();
+  const transport = useMemo(
+    () =>
+      new AssistantChatTransport({
+        api: "/api/chat",
+        resumable: {
+          storage: createResumableSessionStorage({
+            key: () => {
+              const item = aui.threadListItem.getState();
+              return `aui-resumable-stream-id:${item.remoteId ?? item.id}`;
+            },
+          }),
+          resumeApi: (streamId) => `/api/chat/resume/${streamId}`,
+        },
+      }),
+    [aui],
+  );
+  return useChatRuntime({ transport });
+}
+
+export default function Page() {
+  const adapter = useCloudThreadListAdapter({ cloud });
+  const runtime = useRemoteThreadListRuntime({
+    adapter,
+    runtimeHook: ResumableThreadRuntime,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <ThreadList />
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`useCloudThreadListAdapter` is the same adapter `useChatRuntime({ cloud })` builds internally, so cloud thread history and attachments keep working; to bring your own backend, pass a custom `RemoteThreadListAdapter` instead. Each thread's runtime hook constructs its own transport and storage, keyed by that thread's identity, so one conversation's stream id can never be read or cleared by another. `useChatRuntime` is a no-op thread list when nested as a `runtimeHook`, so it only runs the per-thread chat runtime against the per-thread transport; the real thread list is the outer `useRemoteThreadListRuntime`.
+
+Key by `remoteId ?? id` under a recognizable prefix, read lazily. A brand-new thread has no `remoteId` yet, but the transport initializes the thread before the request goes out, so by the time the response header delivers the stream id the getter resolves to the `remoteId`. After a reload the same conversation comes back with that `remoteId` as its id, so the stored entry is found again and the pending stream resumes. The local-id fallback covers a thread that has never sent, whose key nothing else reads or writes. Keying by the local id alone would break resume across reloads for threads created in the current session, because their local `__LOCALID_` id is replaced by the `remoteId` when the list reloads.
+
 ## Storage choices
 
 The core package ships `createInMemoryResumableStreamStore` for development and tests. State lives in a process-local `Map`, so it does not survive a server restart. Useful options include `defaultTtlMs`, `maxChunkBytes`, `maxEntriesPerStream`, `maxStreams`, and `gcIntervalMs` for periodic eviction.

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

@@ -15,13 +15,13 @@ The Suggestions API allows you to configure a list of suggested prompts that are
 Configure suggestions using the `Suggestions()` API in your runtime provider:
 
 ```tsx
-import { useAui, Tools, Suggestions } from "@assistant-ui/react";
+import { AuiConfig, Tools, Suggestions } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   const runtime = useChatRuntime();
 
-  const aui = useAui({
+  const config = AuiConfig({
     tools: Tools({ toolkit: myToolkit }),
     suggestions: Suggestions([
       "What can you help me with?",
@@ -31,7 +31,7 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   });
 
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       {children}
     </AssistantRuntimeProvider>
   );
@@ -45,7 +45,7 @@ Suggestions can be provided as either strings or objects with title, label, and
 ### Simple Strings
 
 ```tsx
-const aui = useAui({
+AuiConfig({
   suggestions: Suggestions([
     "What's the weather today?",
     "Help me write an email",
@@ -59,7 +59,7 @@ const aui = useAui({
 For more detailed suggestions with separate display text and prompts:
 
 ```tsx
-const aui = useAui({
+AuiConfig({
   suggestions: Suggestions([
     {
       title: "Weather",
@@ -315,13 +315,13 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
     ];
   }, [user.isPremium]);
 
-  const aui = useAui({
+  const config = AuiConfig({
     tools: Tools({ toolkit: myToolkit }),
     suggestions: Suggestions(suggestions),
   });
 
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       {children}
     </AssistantRuntimeProvider>
   );
@@ -352,10 +352,10 @@ If your codebase uses the inline `ThreadPrimitive.Suggestion` component (which r
 
 ### Runtime-driven form
 
-1. Configure suggestions in your runtime provider:
+1. Configure suggestions in your runtime provider's `config`:
 
 ```tsx
-const aui = useAui({
+AuiConfig({
   suggestions: Suggestions(["What's the weather?"]),
 });
 ```

package/.docs/raw/docs/ink/hooks.mdx

@@ -41,11 +41,11 @@ import { useAui } from "@assistant-ui/react-ink";
 const aui = useAui();
 
 // Composer actions
-aui.composer().setText("Hello");
-aui.composer().send();
+aui.composer.setText("Hello");
+aui.composer.send();
 
 // Thread actions
-aui.thread().cancelRun();
+aui.thread.cancelRun();
 ```
 
 ### useAuiEvent
@@ -187,12 +187,17 @@ export default defineToolkit({
 ```
 
 ```tsx title="ToolProvider.tsx"
-import { AuiProvider, Tools, useAui } from "@assistant-ui/react-ink";
+import { AuiConfig, AuiProvider, Tools, useAui } from "@assistant-ui/react-ink";
 import toolkit from "./weather-toolkit";
 
 function ToolProvider({ children }: { children: React.ReactNode }) {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 
@@ -271,7 +276,7 @@ export function useWeatherToolkit() {
 }
 ```
 
-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.
+Import the toolkit hook and mount it with `<AuiProvider extends={aui} config={config}>` where `const aui = useAui()` and `const config = AuiConfig({ tools: Tools({ toolkit }) })`, as shown in the [Tools](#tools) section above.
 
 ## Runtime Providers