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

package/.docs/raw/docs/migrations/v0-15.mdx

@@ -224,6 +224,40 @@ return (
 );
 ```
 
+## Thread Switch Events: `threads.selectionChanged`
+
+The per-item thread switch events are deprecated in favor of a single event on the thread list. `threads.selectionChanged` fires once per switch and carries both sides of the transition:
+
+```ts
+// Before
+useAuiEvent("threadListItem.switchedTo", ({ threadId }) => {
+  // threadId: the newly selected thread
+});
+useAuiEvent("threadListItem.switchedAway", ({ threadId }) => {
+  // threadId: the thread that was switched away from
+});
+
+// After
+useAuiEvent("threads.selectionChanged", ({ threadId, previousThreadId }) => {
+  // threadId: the newly selected thread
+  // previousThreadId: the thread that was switched away from
+});
+```
+
+Like its predecessors, it does not fire for the initially selected thread on mount. The deprecated events still fire and will keep working until the next major.
+
+The deprecated pair was scope-filtered: inside a per-item `threadListItem` scope (such as `ThreadListPrimitive.Items`), `threadListItem.switchedTo` only fired for that item. `threads.selectionChanged` resolves against the shared `threads` scope, so every listener fires on every switch. Filter by id to reproduce the per-item behavior:
+
+```ts
+const id = useAuiState((s) => s.threadListItem.id);
+useAuiEvent("threads.selectionChanged", ({ threadId }) => {
+  if (threadId !== id) return;
+  // this item became selected
+});
+```
+
+The new event also fires in situations where the deprecated pair did not: `InMemoryThreadList` emits on selection changes (it previously emitted no switch events), and `switchToNewThread()` emits for the newly created thread. Selection-driven defaults such as `scrollToBottomOnThreadSwitch` and `unstable_focusOnThreadSwitched` now engage in both situations. Runtimes that resolve a deep-linked `threadId`/`initialThreadId` after mount (such as `useRemoteThreadListRuntime`) start on a placeholder new thread, so the deep link's resolution also fires the event — `previousThreadId` is the placeholder in that case.
+
 ## Still Deprecated (not removed)
 
 - Primitive `If` components (`ThreadPrimitive.If`, `MessagePrimitive.If`, `ThreadPrimitive.Empty`) — replaced by `AuiIf`. The codemod migrates these.

package/.docs/raw/docs/primitives/action-bar.mdx

@@ -4,7 +4,7 @@ description: Build message action buttons with auto-hide, copy state, and intell
 platforms: ["react"]
 ---
 
-import { ActionBarPrimitiveSample } from "@/components/docs/samples/action-bar-primitive";
+import { ActionBarPrimitiveSample } from "@/components/pages/docs/samples/action-bar-primitive";
 import { ActionBarPrimitive as ActionBarPrimitiveDocs } from "@/generated/primitiveDocs";
 
 The ActionBar primitive provides message actions: copy, reload, edit, feedback, speech, and export. It handles intelligent visibility with auto-hide on hover, automatic disabling based on message state, and floating behavior. You compose the buttons; the primitive handles action state and availability.

package/.docs/raw/docs/primitives/assistant-modal.mdx

@@ -4,7 +4,7 @@ description: A floating chat popover with a fixed-position trigger button that o
 platforms: ["react"]
 ---
 
-import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";
+import { AssistantModalSample } from "@/components/pages/docs/samples/assistant-modal";
 import { AssistantModalPrimitive as AssistantModalPrimitiveDocs } from "@/generated/primitiveDocs";
 
 The AssistantModal primitive is a floating chat popover built on [Radix Popover](https://www.radix-ui.com/primitives/docs/components/popover). A trigger button opens a chat panel, which is a common floating assistant launcher pattern. You control the trigger, content, positioning, and animations.

package/.docs/raw/docs/primitives/attachment.mdx

@@ -4,7 +4,7 @@ description: File and image attachment rendering for the composer and messages.
 platforms: ["react"]
 ---
 
-import { AttachmentSample } from "@/components/docs/samples/attachment";
+import { AttachmentSample } from "@/components/pages/docs/samples/attachment";
 
 The Attachment primitive renders file and image attachments. It appears in two places: inside the composer for pending uploads (with a remove button), and inside messages for sent attachments (read-only). You provide the layout and styling.
 

package/.docs/raw/docs/primitives/branch-picker.mdx

@@ -4,7 +4,7 @@ description: Navigate between message branches, which are alternative responses
 platforms: ["react"]
 ---
 
-import { BranchPickerPrimitiveSample } from "@/components/docs/samples/branch-picker-primitive";
+import { BranchPickerPrimitiveSample } from "@/components/pages/docs/samples/branch-picker-primitive";
 import { BranchPickerPrimitive as BranchPickerPrimitiveDocs } from "@/generated/primitiveDocs";
 
 The BranchPicker primitive lets users navigate between message branches, which are alternative responses generated by editing a message or regenerating a reply. It's used alongside ActionBar inside message components.

package/.docs/raw/docs/primitives/chain-of-thought.mdx

@@ -4,9 +4,9 @@ description: Collapsible accordion for grouping reasoning steps and tool calls.
 platforms: ["react"]
 ---
 
-import { ChainOfThoughtPrimitiveSample } from "@/components/docs/samples/chain-of-thought-primitive";
-import { ChainOfThoughtPrimitiveSample as ChainOfThoughtPrimitiveSampleRadix } from "@/components/docs/samples/chain-of-thought-primitive.radix";
-import { Flavored } from "@/components/docs/contexts/flavor.server";
+import { ChainOfThoughtPrimitiveSample } from "@/components/pages/docs/samples/chain-of-thought-primitive";
+import { ChainOfThoughtPrimitiveSample as ChainOfThoughtPrimitiveSampleRadix } from "@/components/pages/docs/samples/chain-of-thought-primitive.radix";
+import { Flavored } from "@/components/pages/docs/contexts/flavor.server";
 import {
   ChainOfThoughtPrimitive as ChainOfThoughtPrimitiveDocs,
   MessagePrimitive as MessagePrimitiveDocs,

package/.docs/raw/docs/primitives/composer.mdx

@@ -4,7 +4,7 @@ description: Build custom message input UIs with full control over layout and be
 platforms: ["react"]
 ---
 
-import { ComposerPrimitiveSample } from "@/components/docs/samples/composer-primitive";
+import { ComposerPrimitiveSample } from "@/components/pages/docs/samples/composer-primitive";
 import { ComposerPrimitive as ComposerPrimitiveDocs } from "@/generated/primitiveDocs";
 
 The Composer primitive is the interface for composing new messages or editing existing ones. It handles submit behavior, keyboard shortcuts, focus management, attachment state, and streaming status. You provide the UI.

package/.docs/raw/docs/primitives/error.mdx

@@ -4,7 +4,7 @@ description: Accessible error display for messages with automatic error text ext
 platforms: ["react"]
 ---
 
-import { ErrorPrimitiveSample } from "@/components/docs/samples/error-primitive";
+import { ErrorPrimitiveSample } from "@/components/pages/docs/samples/error-primitive";
 
 The Error primitive renders error states on messages using an accessible `role="alert"` container with automatic error text extraction. `Root` always renders its container; `Message` only renders when the message has an error. Wrap in `MessagePrimitive.Error` if you need the entire block to be conditional.
 

package/.docs/raw/docs/primitives/message.mdx

@@ -4,7 +4,7 @@ description: Build custom message rendering with content parts, attachments, and
 platforms: ["react"]
 ---
 
-import { MessagePrimitiveSample } from "@/components/docs/samples/message-primitive";
+import { MessagePrimitiveSample } from "@/components/pages/docs/samples/message-primitive";
 import { MessagePrimitive as MessagePrimitiveDocs } from "@/generated/primitiveDocs";
 
 The Message primitive handles individual message rendering: content parts, attachments, quotes, hover state, and error display. It's the building block inside each message bubble, resolving text, images, tool calls, and more through a parts pipeline.

package/.docs/raw/docs/primitives/selection-toolbar.mdx

@@ -4,7 +4,7 @@ description: A floating toolbar that appears when text is selected within a mess
 platforms: ["react"]
 ---
 
-import { SelectionToolbarPrimitiveSample } from "@/components/docs/samples/selection-toolbar-primitive";
+import { SelectionToolbarPrimitiveSample } from "@/components/pages/docs/samples/selection-toolbar-primitive";
 
 The SelectionToolbar primitive is a floating toolbar that appears when the user selects text within a message. It lets users quote selected text into the composer. Styling and action layout are fully customizable.
 

package/.docs/raw/docs/primitives/suggestion.mdx

@@ -4,7 +4,7 @@ description: Suggested prompts that users can click to quickly send or populate
 platforms: ["react"]
 ---
 
-import { SuggestionPrimitiveSample } from "@/components/docs/samples/suggestion-primitive";
+import { SuggestionPrimitiveSample } from "@/components/pages/docs/samples/suggestion-primitive";
 import { SuggestionPrimitive as SuggestionPrimitiveDocs } from "@/generated/primitiveDocs";
 
 The Suggestion primitive renders suggested prompts as clickable pills that send a message or populate the composer. Use it for welcome screen suggestions, follow-up prompts, or quick actions. You provide the layout and styling.
@@ -130,11 +130,13 @@ When `send={false}`, the `clearComposer` prop controls whether the suggestion re
 
 ### Static configuration vs. runtime suggestions
 
-There are two separate data flows for suggestions:
+There are two data flows for suggestions:
 
 - **Static configuration** flows through the `suggestions` scope. Pass an array to `Suggestions(...)` in your runtime provider; render it with `ThreadPrimitive.Suggestions`. Best for welcome screen prompts.
 - **Runtime / dynamic suggestions** flow through `thread.suggestions`. Populate it via `SuggestionAdapter` (local runtime) or the `suggestions` field on `useExternalStoreRuntime`; render it with the shadcn `ThreadFollowupSuggestions` component or your own component reading `useAuiState((s) => s.thread.suggestions)`. Best for follow up prompts after a turn.
 
+When no static configuration is provided, the `suggestions` scope derives from `thread.suggestions`, so runtime suggestions also render through `ThreadPrimitive.Suggestions`. A static `Suggestions(...)` configuration takes precedence over the derived values.
+
 See [Suggested Prompts](/docs/guides/suggestions) for end to end examples.
 
 ### ThreadPrimitive.Suggestion (Legacy)

package/.docs/raw/docs/primitives/thread-list.mdx

@@ -4,7 +4,7 @@ description: Multi-thread management for listing, creating, switching, archiving
 platforms: ["react"]
 ---
 
-import { ThreadListPrimitiveSample } from "@/components/docs/samples/thread-list-primitive";
+import { ThreadListPrimitiveSample } from "@/components/pages/docs/samples/thread-list-primitive";
 import { ThreadListPrimitive as ThreadListPrimitiveDocs, ThreadListItemPrimitive as ThreadListItemPrimitiveDocs, ThreadListItemMorePrimitive as ThreadListItemMorePrimitiveDocs } from "@/generated/primitiveDocs";
 
 The ThreadList primitive manages multiple conversations by listing threads, creating new ones, switching between them, and archiving or deleting old ones. It's composed from three primitive namespaces: `ThreadListPrimitive`, `ThreadListItemPrimitive`, and `ThreadListItemMorePrimitive`.

package/.docs/raw/docs/primitives/thread.mdx

@@ -4,7 +4,7 @@ description: Build custom scrollable message containers with auto-scroll, empty
 platforms: ["react"]
 ---
 
-import { ThreadPrimitiveSample } from "@/components/docs/samples/thread-primitive";
+import { ThreadPrimitiveSample } from "@/components/pages/docs/samples/thread-primitive";
 import { ThreadPrimitive as ThreadPrimitiveDocs } from "@/generated/primitiveDocs";
 
 The Thread primitive is the scrollable message container, and the backbone of any chat interface. It handles viewport management, auto-scrolling, empty states, message rendering, and suggestions. You provide the layout and styling.
@@ -143,7 +143,7 @@ Use `topAnchorMessageClamp` to control how much of a long user message remains v
 
 - `scrollToBottomOnRunStart` (default `true`): scrolls when `thread.runStart` fires
 - `scrollToBottomOnInitialize` (default `true`): scrolls when `thread.initialize` fires
-- `scrollToBottomOnThreadSwitch` (default `true`): scrolls when `threadListItem.switchedTo` fires
+- `scrollToBottomOnThreadSwitch` (default `true`): scrolls when `threads.selectionChanged` fires
 
 These work alongside `autoScroll`. If `autoScroll` is omitted, it defaults to `true` for `turnAnchor="bottom"` and `false` for `turnAnchor="top"`.
 

package/.docs/raw/docs/react-native/adapters.mdx

@@ -15,7 +15,7 @@ The simplest way to add persistence. Pass a `cloud` option to `useLocalRuntime`:
 
 ```tsx
 import { useLocalRuntime } from "@assistant-ui/react-native";
-import { AssistantCloud } from "@assistant-ui/cloud";
+import { AssistantCloud } from "assistant-cloud";
 
 const cloud = new AssistantCloud({
   baseUrl: "https://backend.assistant-ui.com",

package/.docs/raw/docs/react-native/index.mdx

@@ -49,7 +49,7 @@ If you prefer to add assistant-ui to an existing Expo project, follow these step
 
 ### Install dependencies
 
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-ai-sdk"]} />
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/ai-sdk"]} />
 
   </Step>
   <Step>
@@ -120,7 +120,7 @@ export async function POST(req: Request) {
 ### Set up the runtime
 
 ```tsx title="hooks/use-app-runtime.ts"
-import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";
 
 const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
 

package/.docs/raw/docs/react-native/migration.mdx

@@ -8,7 +8,7 @@ If you already have an assistant-ui web app, most of your code transfers directl
 ## What stays the same
 
 - **Runtime setup** — `useChatRuntime`, `useLocalRuntime`, `ChatModelAdapter`, and all runtime options work identically.
-- **AI SDK integration** — `@assistant-ui/react-ai-sdk` works with React Native. Your `useChatRuntime` + `AssistantChatTransport` setup transfers directly.
+- **AI SDK integration** — `@assistant-ui/ai-sdk` works with React Native. Your `useChatRuntime` + `AssistantChatTransport` setup transfers directly.
 - **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.
@@ -40,7 +40,7 @@ Your `useChatRuntime` setup works as-is — no changes needed:
 
 ```tsx title="hooks/use-app-runtime.ts"
 // This file is identical to your web version
-import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";
 
 export function useAppRuntime() {
   return useChatRuntime({

package/.docs/raw/docs/react-native/primitives.mdx

@@ -12,7 +12,7 @@ Many primitives share their core logic with `@assistant-ui/react` via `@assistan
 ## Thread
 
 ```tsx
-import { ThreadPrimitive } from "@assistant-ui/react-native";
+import { AuiIf, ThreadPrimitive } from "@assistant-ui/react-native";
 ```
 
 ### ThreadPrimitive.Root
@@ -100,12 +100,17 @@ Renders a single message at a specific index in the thread. Provides message con
 
 ### ThreadPrimitive.Empty
 
-Renders its children only when the thread has no messages. Deprecated in favor of `AuiIf`.
+Renders its children only when the thread is empty (no messages and not loading). Deprecated in favor of `AuiIf`.
 
 ```tsx
 <ThreadPrimitive.Empty>
   <Text>Send a message to get started</Text>
 </ThreadPrimitive.Empty>
+
+// preferred
+<AuiIf condition={(s) => s.thread.isEmpty}>
+  <Text>Send a message to get started</Text>
+</AuiIf>
 ```
 
 ### ThreadPrimitive.If
@@ -117,9 +122,14 @@ Conditional rendering based on thread state. Deprecated in favor of `AuiIf`.
   <Text>No messages yet</Text>
 </ThreadPrimitive.If>
 
-<ThreadPrimitive.If running>
+// preferred
+<AuiIf condition={(s) => s.thread.isEmpty}>
+  <Text>No messages yet</Text>
+</AuiIf>
+
+<AuiIf condition={(s) => s.thread.isRunning}>
   <ActivityIndicator />
-</ThreadPrimitive.If>
+</AuiIf>
 ```
 
 | Prop | Type | Description |
@@ -197,7 +207,10 @@ import { AuiIf } from "@assistant-ui/react-native";
 ## Composer
 
 ```tsx
-import { ComposerPrimitive } from "@assistant-ui/react-native";
+import {
+  ComposerPrimitive,
+  QueueItemPrimitive,
+} from "@assistant-ui/react-native";
 ```
 
 ### ComposerPrimitive.Root
@@ -275,6 +288,79 @@ Renders composer attachments using the provided component configuration.
 </ComposerPrimitive.AddAttachment>
 ```
 
+### ComposerPrimitive.Queue
+
+Renders all queued composer items. Each item is wrapped in a `QueueItemByIndexProvider`, so `QueueItemPrimitive.*` can read item state and call queue actions inside the render prop. Backed by the shared `ComposerPrimitiveQueue` from `@assistant-ui/core/react`.
+
+```tsx
+<ComposerPrimitive.Queue>
+  {({ queueItem }) => (
+    <View>
+      <QueueItemPrimitive.Text />
+      <QueueItemPrimitive.Steer>
+        <Text>Run now</Text>
+      </QueueItemPrimitive.Steer>
+      <QueueItemPrimitive.Remove>
+        <Text>Remove</Text>
+      </QueueItemPrimitive.Remove>
+    </View>
+  )}
+</ComposerPrimitive.Queue>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `(value: { queueItem: QueueItemState }) => ReactNode` | Render function called for each queue item |
+
+### ComposerPrimitive.Quote
+
+Renders the active composer quote preview. Children are only rendered while `s.composer.quote` is set, so this acts as both a container and a gate.
+
+```tsx
+<ComposerPrimitive.Quote>
+  <View>
+    <Text>Quoting:</Text>
+    <ComposerPrimitive.QuoteText />
+    <ComposerPrimitive.QuoteDismiss>
+      <Text>Clear</Text>
+    </ComposerPrimitive.QuoteDismiss>
+  </View>
+</ComposerPrimitive.Quote>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Quote preview content; only rendered when a quote is set |
+| `...rest` | `ViewProps` | Standard React Native View props |
+
+### ComposerPrimitive.QuoteText
+
+Renders the quoted text from `s.composer.quote?.text`. Pass `children` to override the displayed value.
+
+```tsx
+<ComposerPrimitive.QuoteText />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Override content; defaults to `s.composer.quote?.text` |
+| `...rest` | `TextProps` | Standard React Native Text props |
+
+### ComposerPrimitive.QuoteDismiss
+
+`Pressable` that clears the active quote by calling `aui.composer.setQuote(undefined)`.
+
+```tsx
+<ComposerPrimitive.QuoteDismiss>
+  <Text>Clear</Text>
+</ComposerPrimitive.QuoteDismiss>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `PressableProps["children"]` | Button content, including Pressable render-function children |
+| `...rest` | `Omit<PressableProps, "onPress">` | Standard React Native Pressable props except `onPress` |
+
 ### ComposerPrimitive.AttachmentByIndex
 
 Renders a single composer attachment at the specified index. Useful for building custom attachment layouts.
@@ -557,6 +643,57 @@ Container `View` for an attachment.
 </AttachmentPrimitive.Remove>
 ```
 
+## QueueItem
+
+```tsx
+import { QueueItemPrimitive } from "@assistant-ui/react-native";
+```
+
+Primitives for rendering individual queued composer items. Use inside a `ComposerPrimitive.Queue` render prop, where the queue item context is set up by `QueueItemByIndexProvider`.
+
+### QueueItemPrimitive.Text
+
+Renders the queue item's text with React Native `<Text>`. Pass `children` to override the displayed value.
+
+```tsx
+<QueueItemPrimitive.Text />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Override content; defaults to the text parts of `s.queueItem.parts` |
+| `...rest` | `TextProps` | Standard React Native Text props |
+
+### QueueItemPrimitive.Remove
+
+`Pressable` that removes the queue item by calling `aui.queueItem.remove()`.
+
+```tsx
+<QueueItemPrimitive.Remove>
+  <Text>Remove</Text>
+</QueueItemPrimitive.Remove>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `PressableProps["children"]` | Button content, including Pressable render-function children |
+| `...rest` | `Omit<PressableProps, "onPress">` | Standard React Native Pressable props except `onPress` |
+
+### QueueItemPrimitive.Steer
+
+`Pressable` that promotes the queue item to run next by calling `aui.queueItem.steer()`.
+
+```tsx
+<QueueItemPrimitive.Steer>
+  <Text>Run now</Text>
+</QueueItemPrimitive.Steer>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `PressableProps["children"]` | Button content, including Pressable render-function children |
+| `...rest` | `Omit<PressableProps, "onPress">` | Standard React Native Pressable props except `onPress` |
+
 ## ActionBar
 
 ```tsx

package/.docs/raw/docs/runtimes/ag-ui/runtime-options.mdx

@@ -1,6 +1,6 @@
 ---
 title: Runtime options
-description: useAgUiRuntime options, adapters, supported events, thread list.
+description: useAgUiRuntime options, adapters, message conversion, thread list.
 ---
 
 import { AguiIcon } from "@/components/icons/agui";
@@ -16,7 +16,7 @@ Reference for the runtime's API surface. Start with [quickstart](/docs/runtimes/
 | `showThinking` | `boolean` | Whether to render `THINKING_*` and `REASONING_*` events as visible reasoning. Defaults to `true`. |
 | `autoCancelPendingToolCalls` | `boolean` | Cancel unresolved client-side tool calls automatically when the user sends, edits, or reloads a message. Defaults to `true`. See [below](#auto-cancelling-pending-tool-calls). |
 | `onError` | `(e: Error) => void` | Error callback fired on `RUN_ERROR` events and protocol errors. |
-| `onCancel` | `() => void` | Cancellation callback fired when the user cancels a run. |
+| `onCancel` | `() => void` | Cancellation callback fired when a run is cancelled, including user cancel and runtime teardown. |
 | `adapters` | `UseAgUiRuntimeAdapters` | Standard adapter slots (see below). |
 
 ## Adapter slots
@@ -64,8 +64,20 @@ messages are gone on the next page load.
 
 `fromAgUiMessages` accepts an optional second argument: pass
 `{ showThinking: false }` to match a runtime configured with
-`showThinking: false`, so imported reasoning messages are dropped at conversion
-time, the same way a live run never stores them.
+`showThinking: false`, so the readable text of an imported reasoning message is
+dropped at conversion time, the same way a live run never stores it. An
+`encryptedValue` on that message is kept, because it is opaque state the agent
+needs back rather than something the option hides.
+
+Reasoning makes the round trip in the shape it arrived in. `fromAgUiMessages` imports a `reasoning` record as an assistant message holding a reasoning part, and the run input converts that part back into a standalone `reasoning` record instead of dropping it, so a reloaded thread keeps its reasoning history on the next run. A reasoning part on an assistant message that also has text or tool calls leaves as its own `reasoning` record placed ahead of that assistant record; the AG-UI message body carries no run identity, so the original position of reasoning within a run is not recoverable.
+
+The encrypted value survives with it. AG-UI describes it as an opaque chain-of-thought blob the client stores and forwards for state continuity, not as a signature computed over the text. An imported `ReasoningMessage` carrying `encryptedValue` keeps it at `providerMetadata.agui.encryptedValue` on the part, and a live run picks the same value up from the `REASONING_ENCRYPTED_VALUE` event (`subtype: "message"`, keyed by `entityId`), so reasoning from either source is re-emitted with the value intact and an agent that needs it back can replay it. A record whose readable `content` is empty and whose payload lives entirely in `encryptedValue`, the zero-data-retention shape AG-UI describes when an agent advertises `capabilities.reasoning.encrypted`, is preserved on the import path only. It has nothing to render by construction, so it never becomes a message or a part; it rides on `metadata.custom.agui.opaqueReasoning` of the message it sat next to on the wire and is replayed into the run input adjacent to that message. `showThinking` does not discard it. That option hides reasoning from the UI, and the encrypted value is opaque state the agent needs back rather than something rendered, so a hidden record keeps it and loses only the readable text. This is an import-path guarantee: a live run with `showThinking: false` opens no reasoning block, so a `REASONING_ENCRYPTED_VALUE` arriving during it resolves no slot and is not retained. The same thread therefore carries the value after a reload but not within the live session that produced it. A consumer calling `fromAgUiMessages` directly sees the metadata rather than a part.
+
+Three limits apply to that record. A live stream that emits no readable content produces no reasoning part, so the runtime has nothing to attach the value to; only `fromAgUiMessages` preserves it, whether you call it yourself or the runtime calls it for you while importing a `MESSAGES_SNAPSHOT`. A record that sat between an assistant message and its own tool result is replayed after that tool result rather than between the two, because the import folds the result into the assistant message and the boundary is gone by export. A record in a snapshot that contains no other message has nothing to anchor to and is dropped.
+
+Sending reasoning back is what the protocol asks for, and the inbound side has to handle it. `ag-ui-langgraph` is worth pinning for that reason: below 0.0.36 it raises `ValueError: Unsupported message role: reasoning` on the second turn of any thread that produced reasoning, because its converter recognised only the user, assistant, system, and tool roles. 0.0.36 skips inbound `reasoning` and `developer` records instead of raising, so the turn succeeds but the reasoning is discarded. 0.0.42 re-attaches an inbound `reasoning` record as a content block on the assistant message that follows it, encrypted content included, so the replay actually reaches the model; a record that no assistant message follows is still discarded there, which is what becomes of one replayed after the last message of a thread. Keep it at 0.0.36 or newer to avoid the error, and at 0.0.42 or newer for the replay to be worth anything.
+
+What a server does with a replayed record remains its own choice, so treat continuity as best effort rather than guaranteed. `ag-ui-langgraph` covers all three behaviours across those three versions, and another integration may pick any of them; an `encryptedValue` reaches the provider only where the server forwards it.
 
 `fromAgUiMessages` reconstructs the text, reasoning, and tool calls of each message. Multimodal user input (`image`, `audio`, `video`, and `document` parts, as well as legacy `binary` parts) is restored as attachments on the user message, so a backend that persists multimodal messages shows them again on reload and re-sends them on the next run. Legacy `binary` parts that only reference a file id are not restored.
 
@@ -73,6 +85,18 @@ An assistant message whose tool call has no matching tool result is reconstructe
 
 Interrupts are restored when your backend persists them on the assistant message. The AG-UI message body has no interrupt field, so persist the runtime's own `metadata.custom.agui.interrupts` array alongside the message; `fromAgUiMessages` reads it back, reconstructs `requires-action` / `interrupt` status, and re-attaches the metadata, so `getPendingInterrupts`, `useAgUiInterrupts`, and `submitInterruptResponses` work on reload. When both a pending tool call and an interrupt are present on the same message, interrupt status wins. Without the persisted array, interrupt state cannot be reconstructed.
 
+## Building AG-UI run input
+
+`toAgUiMessages` is the converter the runtime uses to build `runAgent` input. Use it when you own the transport, for example an AG-UI WebSocket, and need the same conversion from `onNew`'s `AppendMessage`:
+
+```tsx
+import { toAgUiMessages } from "@assistant-ui/react-ag-ui";
+
+const [agUiMessage] = toAgUiMessages([message]);
+```
+
+`AppendMessage` has no `id`. The converter assigns one so the AG-UI message schema is satisfied. A caller-supplied id is kept. A generated id is new on every call, so convert once and send that object. Only `user`, `assistant`, `system`, `developer`, `tool`, and `reasoning` inputs are converted.
+
 ## Thread list (experimental)
 
 <Callout type="warn">
@@ -183,8 +207,25 @@ The runtime parses the AG-UI event stream and maps each event type to assistant-
 | `STATE_SNAPSHOT` | Replaces the agent's external state. |
 | `STATE_DELTA` | Applies a JSON-patch-style delta to the agent's state. |
 | `MESSAGES_SNAPSHOT` | Replaces the full message list (used for thread restore). |
-| `CUSTOM` | Forwarded to your custom event handling. |
-| `RAW` | Untyped passthrough for unrecognized events. |
+| `CUSTOM` | Appended to the in-flight assistant message as a `data` part. |
+| `RAW` | Parsed and ignored; unrecognized wire event types are normalized into `RAW`. |
+
+### Custom events
+
+`CUSTOM` events are the protocol's extension mechanism for application-defined data. Each event is appended to the in-flight assistant message as a canonical `data` part in arrival order: `CUSTOM { name: "sources", value: {...} }` becomes `{ type: "data", name: "sources", data: {...} }`. Repeated names append separate parts, the `value` is passed through verbatim, and data parts reset with each run. Tool calls that carry a `parentMessageId` are anchored under that message rather than at their wire position, so a data part can render after a tool call that arrived later. A run that delivers its assistant message only through `MESSAGES_SNAPSHOT`, with no streamed text or tool calls, drops that run's data parts when the snapshot supersedes the in-flight message.
+
+Render them by registering a per-name renderer; parts without a registered renderer are not displayed, unless a `Data` fallback component is registered, in which case the fallback receives every custom event name, including the framework plumbing listed below.
+
+```tsx
+import { useAssistantDataUI } from "@assistant-ui/react";
+
+useAssistantDataUI({
+  name: "sources",
+  render: ({ data }) => <SourceList sources={data.sources} />,
+});
+```
+
+Data parts stay in the assistant-ui message but are not sent back to the agent, since the AG-UI assistant record has no field for them. History adapters, including the assistant-cloud one, persist them as part of the message JSON. Framework integrations emit their own plumbing over this channel (`on_interrupt`, `PredictState`, `Exit`, `hook_error`, `state_update_error`, `system:*`, `MultiAgentHandoff`), and those names surface as data parts like any other, so only register renderers for names your backend owns.
 
 ## Feature support
 
@@ -195,6 +236,7 @@ The runtime parses the AG-UI event stream and maps each event type to assistant-
 | Tool calls and results | Yes |
 | Tool result handoff (client-side execution) | Yes |
 | State snapshots and deltas | Yes |
+| Custom events (as `data` parts) | Yes |
 | Cancellation | Yes |
 | Message editing | Yes |
 | Message reload | Yes |

package/.docs/raw/docs/runtimes/ai-sdk/overview.mdx

@@ -5,13 +5,13 @@ description: Connect the Vercel AI SDK to a React chat UI via assistant-ui — u
 
 import { VercelIcon } from "@/components/icons/vercel";
 
-`@assistant-ui/react-ai-sdk` integrates assistant-ui with the [Vercel AI SDK](https://ai-sdk.dev/). It covers `useChat` flows, custom transports, frontend tools, attachments, quote context, multi-step agents, token usage, and cloud persistence.
+`@assistant-ui/ai-sdk` integrates assistant-ui with the [Vercel AI SDK](https://ai-sdk.dev/). It covers `useChat` flows, custom transports, frontend tools, attachments, quote context, multi-step agents, token usage, and cloud persistence.
 
 ## Pick a version
 
 | AI SDK | Runtime package | Docs |
 | --- | --- | --- |
-| `ai@^7` + `@ai-sdk/react@^4` | `@assistant-ui/react-ai-sdk@^1.4` (latest) | [v7 (current)](/docs/runtimes/ai-sdk/v7) |
+| `ai@^7` + `@ai-sdk/react@^4` | `@assistant-ui/ai-sdk` (latest) | [v7 (current)](/docs/runtimes/ai-sdk/v7) |
 | `ai@^6` + `@ai-sdk/react@^3` | `@assistant-ui/react-ai-sdk@1.3.40` | [v6 (legacy)](/docs/runtimes/ai-sdk/v6-legacy) |
 | `ai@^5` + `@ai-sdk/react@^2` | `@assistant-ui/react-ai-sdk@1.1.21` | [v5 (legacy)](/docs/runtimes/ai-sdk/v5-legacy) |
 | `ai@^4` | `@assistant-ui/react-data-stream` | [v4 (legacy)](/docs/runtimes/ai-sdk/v4-legacy) |
@@ -20,7 +20,7 @@ New projects should target v7. v6, v5, and v4 are documented for projects that h
 
 ## Architecture
 
-`@assistant-ui/react-ai-sdk` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Features that ship as runtime adapters work the same way they do everywhere else; see [adapters](/docs/runtimes/concepts/adapters).
+`@assistant-ui/ai-sdk` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Features that ship as runtime adapters work the same way they do everywhere else; see [adapters](/docs/runtimes/concepts/adapters).
 
 For reload-safe streaming (persist an in-flight response so the client can reconnect), see [Resumable Streams](/docs/guides/resumable-streams).
 

package/.docs/raw/docs/runtimes/ai-sdk/v4-legacy.mdx

@@ -6,12 +6,12 @@ description: Reference for projects still on AI SDK v4. New projects should use
 import { VercelIcon } from "@/components/icons/vercel";
 
 <Callout type="warn">
-AI SDK v4 is a legacy version. New projects should use [AI SDK v7](/docs/runtimes/ai-sdk/v7). v4 integrations use the older `@assistant-ui/react-data-stream` package, not `@assistant-ui/react-ai-sdk`.
+AI SDK v4 is a legacy version. New projects should use [AI SDK v7](/docs/runtimes/ai-sdk/v7). v4 integrations use the older `@assistant-ui/react-data-stream` package, not `@assistant-ui/ai-sdk`.
 </Callout>
 
 ## Why legacy
 
-Vercel ships AI SDK majors roughly yearly; v4 is three majors behind v7. The current `@assistant-ui/react-ai-sdk` package targets the current AI SDK major (v7) exclusively, so v4 users plug into [`@assistant-ui/react-data-stream`](/docs/runtimes/custom/data-stream) instead — the same data stream protocol that v4's `toDataStreamResponse()` emits.
+Vercel ships AI SDK majors roughly yearly; v4 is three majors behind v7. The current `@assistant-ui/ai-sdk` package targets the current AI SDK major (v7) exclusively, so v4 users plug into [`@assistant-ui/react-data-stream`](/docs/runtimes/custom/data-stream) instead — the same data stream protocol that v4's `toDataStreamResponse()` emits.
 
 This page is reference for existing v4 projects. Plan to migrate to v7 when feasible.
 
@@ -79,7 +79,7 @@ detects it automatically. If a custom proxy strips or hides that header, pass
 | Feature | v4 | v6 |
 | --- | --- | --- |
 | `ai` package | `ai@^4` | `ai@^6` |
-| Runtime package | `@assistant-ui/react-data-stream` | `@assistant-ui/react-ai-sdk` |
+| Runtime package | `@assistant-ui/react-data-stream` | `@assistant-ui/react-ai-sdk@1.3.40` |
 | Runtime hook | `useDataStreamRuntime` | `useChatRuntime` |
 | Response | `toDataStreamResponse()` | `toUIMessageStreamResponse()` |
 | Tool schema | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
@@ -89,7 +89,7 @@ detects it automatically. If a custom proxy strips or hides that header, pass
 
 When you are ready to upgrade:
 
-1. Swap `@assistant-ui/react-data-stream` for `@assistant-ui/react-ai-sdk`.
+1. Swap `@assistant-ui/react-data-stream` for `@assistant-ui/ai-sdk`.
 2. Update your backend to the current AI SDK's `streamText` (see [v7 docs](/docs/runtimes/ai-sdk/v7)).
 3. Switch the runtime hook from `useDataStreamRuntime` to `useChatRuntime`.