@assistant-ui/mcp-docs-server 0.2.0 → 0.2.2

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

@@ -283,7 +283,7 @@ This pattern records until the user stops dictation, then commits a single final
 
 ## Custom realtime providers
 
-You can implement `DictationAdapter` against any streaming STT service. [ElevenLabs Scribe](https://elevenlabs.io/docs/capabilities/speech-to-text) is one option for low-latency WebSocket transcription; scaffold a full example with:
+You can implement `DictationAdapter` against any streaming STT service. [ElevenLabs Scribe](https://elevenlabs.io/docs/overview/capabilities/speech-to-text) is one option for low-latency WebSocket transcription; scaffold a full example with:
 
 ```bash
 npx assistant-ui create my-app -e with-elevenlabs-scribe

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

@@ -214,7 +214,7 @@ export function registerAssistantIpc(mainWindow: BrowserWindow) {
     void (async () => {
       try {
         const result = streamText({
-          model: openai("gpt-5.4-mini"),
+          model: openai("gpt-5.6-luna"),
           messages: request.messages,
           ...(request.system ? { system: request.system } : {}),
           abortSignal: abortController.signal,

package/.docs/raw/docs/guides/mentions.mdx

@@ -82,6 +82,8 @@ const myAdapter: Unstable_TriggerAdapter = {
 
 The built-in `unstable_useLiveCompletionAdapter` wraps an async fetcher with debouncing, stale-request cancellation (results for an outdated query are dropped), and a single-entry cache. Its `search` returns the last results synchronously and schedules a debounced fetch when the query changes; when results arrive the returned `adapter` re-creates, which re-runs the popover lookup so the fresh items render. It also reports `isLoading`, which you pass to the popover to show a loading state.
 
+When the fetcher reads from an account- or workspace-specific source, pass that source ID as `cacheKey`. Changing the key clears cached results and cancels any pending result from the previous source.
+
 ```tsx
 import {
   unstable_useLiveCompletionAdapter,

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",
@@ -138,7 +138,7 @@ The primitives available for rendering suggestions are `ThreadPrimitive.Suggesti
 
 ## Runtime driven suggestions
 
-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.
+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`, and when no static `Suggestions(...)` configuration is set, the `suggestions` scope derives from them, so `ThreadPrimitive.Suggestions` renders them as well. Runtime suggestions use the `ThreadSuggestion` shape: a required `prompt` plus optional `title` and `label`. When `title` is omitted it falls back to the prompt, and an omitted `label` renders as empty, so a prompt-only runtime suggestion looks exactly like a plain string suggestion.
 
 ### Local runtime: `SuggestionAdapter`
 
@@ -263,7 +263,7 @@ The local runtime clears its suggestions when a new run starts. External store r
 
 ### 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:
+Runtime suggestions land on `thread.suggestions`, and `ThreadPrimitive.Suggestions` picks them up unless a static `Suggestions(...)` configuration overrides the scope. 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";
@@ -280,7 +280,10 @@ function FollowUps() {
             method="replace"
             autoSend
           >
-            {s.prompt}
+            {s.title ?? s.prompt}
+            {s.label && (
+              <span className="text-muted-foreground ms-1">{s.label}</span>
+            )}
           </ThreadPrimitive.Suggestion>
         ))}
       </div>
@@ -315,13 +318,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 +355,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

@@ -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
 

package/.docs/raw/docs/ink/primitives.mdx

@@ -666,10 +666,11 @@ Container `Box` for an attachment. Forwards all `Box` props.
 
 ### Thumb
 
-`Text` component displaying a short identifier for the attachment. Renders the file extension (`.pdf`, `.png`, …) when the name has one. Falls back to the attachment `type` (e.g. `image`, `document`) otherwise, and finally to `file`.
+`Text` component displaying a short identifier for the attachment. Renders the file extension (`.pdf`, `.png`, …) when the name has one. Falls back to the attachment `type` (e.g. `image`, `document`) otherwise, and finally to `file`. Passing `children` overrides the automatic label.
 
 | Prop | Type | Description |
 |------|------|-------------|
+| `children` | `ReactNode` | Overrides the automatic extension/type label |
 | `...rest` | `ComponentProps<typeof Text>` | Forwarded to the underlying Ink `Text` |
 
 ### Status
@@ -712,7 +713,7 @@ Primitives for rendering individual queued composer items. Use inside a `Compose
 
 ### Text
 
-Renders the queue item's prompt with Ink `<Text>`. Pass `children` to override the displayed value.
+Renders the queue item's text with Ink `<Text>`. Pass `children` to override the displayed value.
 
 ```tsx
 <QueueItemPrimitive.Text color="gray" />
@@ -720,7 +721,7 @@ Renders the queue item's prompt with Ink `<Text>`. Pass `children` to override t
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `children` | `ReactNode` | Override content; defaults to `s.queueItem.prompt` |
+| `children` | `ReactNode` | Override content; defaults to the text parts of `s.queueItem.parts` |
 | `...rest` | `TextProps` | Standard Ink Text props |
 
 ### Remove
@@ -1216,7 +1217,7 @@ Container `Box` for the status bar. Forwards all `Box` props; pass `gap` to spac
 ```tsx
 <StatusBarPrimitive.Root gap={1}>
   <StatusBarPrimitive.Status />
-  <StatusBarPrimitive.ModelName name="gpt-5" />
+  <StatusBarPrimitive.ModelName name="gpt-5.6-luna" />
   <StatusBarPrimitive.MessageCount />
   <StatusBarPrimitive.TokenCount />
   <StatusBarPrimitive.Latency />

package/.docs/raw/docs/integrations/attachments/custom-adapter.mdx

@@ -489,6 +489,22 @@ In the adapter's `add`, call Uploadthing's client upload and read `url` from the
 </Tab>
 </Tabs>
 
+### Opaque file references (LangGraph / LangChain)
+
+When the backend resolves stored files itself and the browser never holds a usable URL, send the storage id instead: set `sourceType: "id"` on the file part in `send()`, and the LangChain-family runtimes emit a `source_type: "id"` block with the value in the `id` key. `sourceType: "url"` similarly forces a url reference for non-http data and is honored by the LangChain-family, A2A, AG-UI, and Google ADK runtimes. `sourceType: "id"` is LangChain-family only; runtimes without the concept ignore the field.
+
+```ts
+const content = [
+  {
+    type: "file" as const,
+    filename: name,
+    mimeType: contentType ?? "application/octet-stream",
+    data: fileId,
+    sourceType: "id" as const,
+  },
+];
+```
+
 ## Notes
 
 - **Persistence.** A URL the model sees on Monday must still resolve next week if the thread is reloaded. Either use storage with no expiry on the public URL, or have your [history adapter](/docs/integrations/persistence/custom-adapter) regenerate signed URLs on `load`. Don't store presigned URLs in the message row.

package/.docs/raw/docs/integrations/auth/better-auth.mdx

@@ -66,7 +66,7 @@ export async function POST(req: Request) {
 
   const { messages }: { messages: UIMessage[] } = await req.json();
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
   });
   return result.toUIMessageStreamResponse();

package/.docs/raw/docs/integrations/auth/clerk.mdx

@@ -45,7 +45,7 @@ export async function POST(req: Request) {
 
   const { messages }: { messages: UIMessage[] } = await req.json();
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
   });
   return result.toUIMessageStreamResponse();

package/.docs/raw/docs/integrations/auth/next-auth.mdx

@@ -72,7 +72,7 @@ export async function POST(req: Request) {
 
   const { messages }: { messages: UIMessage[] } = await req.json();
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
   });
   return result.toUIMessageStreamResponse();

package/.docs/raw/docs/integrations/frameworks/cloudflare-agents/overview.mdx

@@ -68,7 +68,7 @@ export type Env = {
 export class Chat extends AIChatAgent<Env> {
   async onChatMessage(onFinish: Parameters<typeof streamText>[0]["onFinish"]) {
     return streamText({
-      model: openai("gpt-5.4-nano"),
+      model: openai("gpt-5.6-luna"),
       messages: await convertToModelMessages(this.messages),
       onFinish,
     });

package/.docs/raw/docs/integrations/frameworks/mastra/full-stack.mdx

@@ -81,11 +81,11 @@ export const chefAgent = new Agent({
   instructions:
     "You are Michel, a practical and experienced home chef. " +
     "You help people cook with whatever ingredients they have available.",
-  model: "openai/gpt-5.4-mini",
+  model: "openai/gpt-5.6-luna",
 });
 ```
 
-`model: "openai/gpt-5.4-mini"` uses Mastra's model router. Set the provider key in `.env.local` so Next.js auto-loads it:
+`model: "openai/gpt-5.6-luna"` uses Mastra's model router. Set the provider key in `.env.local` so Next.js auto-loads it:
 
 ```sh title=".env.local"
 OPENAI_API_KEY=sk-...

package/.docs/raw/docs/integrations/frameworks/mastra/separate-server.mdx

@@ -50,7 +50,7 @@ export const chefAgent = new Agent({
   instructions:
     "You are Michel, a practical and experienced home chef. " +
     "You help people cook with whatever ingredients they have available.",
-  model: "openai/gpt-5.4-nano",
+  model: "openai/gpt-5.6-luna",
 });
 ```
 

package/.docs/raw/docs/integrations/gateways/index.mdx

@@ -48,7 +48,7 @@ The rest of this page is what to put in `baseURL`, `headers`, and `model(...)` f
 
 ## OpenRouter
 
-[OpenRouter](https://openrouter.ai/) aggregates 100+ models behind one OpenAI-compatible endpoint. The model ID is `provider/model` (e.g., `anthropic/claude-sonnet-4.6`, `openai/gpt-5.4-mini`, `meta-llama/llama-3.3-70b-instruct`).
+[OpenRouter](https://openrouter.ai/) aggregates 100+ models behind one OpenAI-compatible endpoint. The model ID is `provider/model` (e.g., `anthropic/claude-sonnet-4.6`, `openai/gpt-5.6-luna`, `meta-llama/llama-3.3-70b-instruct`).
 
 ```sh title=".env.local"
 OPENROUTER_API_KEY=sk-or-...
@@ -129,7 +129,7 @@ const litellm = createOpenAI({
 });
 
 const result = streamText({
-  model: litellm("gpt-5.4-mini"),
+  model: litellm("gpt-5.6-luna"),
   messages: await convertToModelMessages(messages),
 });
 ```

package/.docs/raw/docs/integrations/observability/helicone.mdx

@@ -57,7 +57,7 @@ const openai = createOpenAI({
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
   });
   return result.toUIMessageStreamResponse();
@@ -80,7 +80,7 @@ const openai = new OpenAI({
 export async function POST(req: Request) {
   const { messages } = await req.json();
   const stream = await openai.chat.completions.create({
-    model: "gpt-5.4-mini",
+    model: "gpt-5.6-luna",
     messages,
     stream: true,
   });

package/.docs/raw/docs/integrations/observability/langfuse.mdx

@@ -101,7 +101,7 @@ export async function POST(req: Request) {
     { traceName: "chat-completion", userId, sessionId },
     async () =>
       streamText({
-        model: openai("gpt-5.4-nano"),
+        model: openai("gpt-5.6-luna"),
         messages: await convertToModelMessages(messages),
         experimental_telemetry: { isEnabled: true },
       }),

package/.docs/raw/docs/integrations/observability/langsmith.mdx

@@ -63,7 +63,7 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages: await ai.convertToModelMessages(messages),
   });
 
@@ -84,7 +84,7 @@ Pass a `langsmith` provider option to tag traces with user, session, or run iden
 import { createLangSmithProviderOptions } from "langsmith/experimental/vercel";
 
 const result = streamText({
-  model: openai("gpt-5.4-nano"),
+  model: openai("gpt-5.6-luna"),
   messages: await ai.convertToModelMessages(messages),
   providerOptions: {
     langsmith: createLangSmithProviderOptions({