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

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

@@ -9,14 +9,14 @@ import { VercelIcon } from "@/components/icons/vercel";
 [Cloudflare Agents](https://developers.cloudflare.com/agents/) is Cloudflare's framework for stateful AI agents that run on Durable Objects at the edge. Each agent owns its own SQLite-backed message history, exposes a WebSocket channel for low-latency streaming, and can call tools (server-side or client-side).
 
 <Callout type="info">
-This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-cloudflare-agents` package. `@cloudflare/ai-chat`'s `useAgentChat` returns a structural extension of the AI SDK's `useChat`, so the existing [AI SDK runtime](/docs/runtimes/ai-sdk/v6) consumes it directly.
+This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-cloudflare-agents` package. `@cloudflare/ai-chat`'s `useAgentChat` returns a structural extension of the AI SDK's `useChat`, so the existing [AI SDK runtime](/docs/runtimes/ai-sdk/v7) consumes it directly.
 </Callout>
 
 ## Architecture
 
 Cloudflare Agents handles the server half: a Durable Object subclasses `AIChatAgent` from `@cloudflare/ai-chat`, owns the message history, and streams responses back over a WebSocket. `@cloudflare/ai-chat/react`'s `useAgentChat` hook wraps that WebSocket and exposes the same `messages`, `sendMessage`, `regenerate`, `status`, `stop`, `setMessages`, `addToolOutput` surface that the AI SDK's `useChat` does, plus a few Cloudflare-specific extras (`clearHistory`, `isServerStreaming`, `isToolContinuation`).
 
-assistant-ui handles the client half. `useAISDKRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v6) reads exactly those AI SDK methods off whatever you pass in, so feeding it `useAgentChat`'s return value yields a fully-featured runtime: streaming, tool calling, edit, reload, history import and export, attachments, suggestions.
+assistant-ui handles the client half. `useAISDKRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v7) reads exactly those AI SDK methods off whatever you pass in, so feeding it `useAgentChat`'s return value yields a fully-featured runtime: streaming, tool calling, edit, reload, history import and export, attachments, suggestions.
 
 Shared adapters (attachments, speech, feedback, history) work the same way as described in [adapters](/docs/runtimes/concepts/adapters). Multi-thread support needs a [custom thread list](/docs/runtimes/concepts/threads) wired around `useAISDKRuntime`; [AssistantCloud](/docs/cloud) integrates via `useChatRuntime` (which constructs its own `useChat` internally) and is not compatible with the `useAgentChat` wiring shown here.
 
@@ -277,6 +277,6 @@ Destructure these alongside `chat` and pass them into your UI directly; they don
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

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

@@ -183,6 +183,6 @@ Open `http://localhost:3000`, send a message like *"What can I make with eggs an
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/overview.mdx

@@ -9,7 +9,7 @@ import { VercelIcon } from "@/components/icons/vercel";
 [Mastra](https://mastra.ai/) is an open-source TypeScript agent framework. It provides primitives for AI applications: agents with memory and tool calling, deterministic LLM workflows, RAG, model routing, workflow graphs, and automated evals.
 
 <Callout type="info">
-This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-mastra` package. You wire up Mastra through the standard [AI SDK runtime](/docs/runtimes/ai-sdk/v6) by routing your API endpoint through Mastra's agent stream.
+This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-mastra` package. You wire up Mastra through the standard [AI SDK runtime](/docs/runtimes/ai-sdk/v7) by routing your API endpoint through Mastra's agent stream.
 </Callout>
 
 ## Pick a pattern
@@ -19,7 +19,7 @@ This is an integration guide, not a runtime adapter. assistant-ui does not ship
 | [Full-stack](/docs/integrations/frameworks/mastra/full-stack) | One Next.js app: API routes call Mastra in-process. Simpler deployment, single repo. |
 | [Separate server](/docs/integrations/frameworks/mastra/separate-server) | Mastra runs as its own service; the Next.js frontend hits its API. Independent scaling, clearer separation of concerns. |
 
-Both use the same client-side `useChatRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v6). The only difference is where the Mastra agent lives.
+Both use the same client-side `useChatRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v7). The only difference is where the Mastra agent lives.
 
 ## Architecture
 
@@ -52,6 +52,6 @@ Shared adapters (attachments, speech, feedback, history) work the same way descr
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

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

@@ -196,6 +196,6 @@ Open `http://localhost:3000`, send a message, and confirm:
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

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

@@ -8,7 +8,7 @@ import { VercelIcon } from "@/components/icons/vercel";
 
 LLM gateways sit between your route handler and the upstream provider. They give you a single endpoint that fronts many providers, plus features like multi-provider fallback, prompt caching, and BYOK (bring-your-own-key) flows. Most are OpenAI API-compatible, so the integration is a `baseURL` swap on `createOpenAI` from `@ai-sdk/openai`.
 
-For pure observability (proxy that logs every call) see [Helicone](/docs/integrations/observability/helicone). The gateways here overlap in spirit but are positioned around routing rather than logging.
+For pure observability (proxy that logs every call) see [Helicone](/docs/integrations/observability/helicone). The gateways here overlap in spirit but are positioned around routing rather than logging. For local personal projects there is also a keyless option in the same `baseURL`-swap shape: a local OAuth proxy billed to your ChatGPT subscription; see [ChatGPT Subscription](/docs/guides/chatgpt-subscription).
 
 ## Compare
 
@@ -157,6 +157,6 @@ When to pick: self-host requirement, BYOK metering for end-users, or unified bil
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that ferries gateway responses to the chat UI."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

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

@@ -158,7 +158,7 @@ Upload chat attachments to object storage instead of inlining as data URLs.
 assistant-ui doesn't ship a guide for every tool, but most fit one of two patterns:
 
 - **Routes through your AI SDK handler** (agent frameworks, observability proxies, gateways): adapt the [Mastra full-stack](/docs/integrations/frameworks/mastra/full-stack) or [Helicone proxy](/docs/integrations/observability/helicone) pattern using the service's own SDK.
-- **Replaces the runtime entirely** (custom backends): see [custom backend](/docs/runtimes/custom).
+- **Replaces the runtime entirely** (custom backends): see [custom backend](/docs/runtimes/custom/overview).
 
 If you build something useful, [open an issue](https://github.com/assistant-ui/assistant-ui/issues) or post in [Discord](https://discord.gg/S9dwgCNEFs); the docs are open to contributions.
 

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

@@ -124,6 +124,6 @@ If nothing appears, check the request in your network tab. The host should be `o
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The most common pairing: AI SDK route handler proxied through Helicone."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

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

@@ -156,6 +156,6 @@ If nothing appears, check the server logs for OTel errors and confirm `LANGFUSE_
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that emits the telemetry Langfuse consumes."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

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

@@ -9,7 +9,7 @@ import { VercelIcon } from "@/components/icons/vercel";
 
 [LangSmith](https://www.langchain.com/langsmith) is LangChain's observability and eval platform. If you are already in the LangChain or LangGraph ecosystem, LangSmith is the natural pairing: traces, datasets, prompt versioning, and LLM-as-judge evals share state with the rest of the LangChain stack.
 
-This page covers the **AI SDK** path. If you use [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph), tracing flows through LangGraph Cloud automatically; you only need this guide when your route handler talks to AI SDK directly.
+This page covers the **AI SDK** path. If you use [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph/overview), tracing flows through LangGraph Cloud automatically; you only need this guide when your route handler talks to AI SDK directly.
 
 ## How it works
 
@@ -134,7 +134,7 @@ Send a message. The trace should appear in your LangSmith project within seconds
     icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
     title="LangGraph runtime"
     description="If your backend is LangGraph, tracing flows through LangGraph Cloud automatically."
-    href="/docs/runtimes/langgraph"
+    href="/docs/runtimes/langgraph/overview"
   />
   <Card
     icon={<LangfuseIcon width={20} height={20} />}
@@ -146,6 +146,6 @@ Send a message. The trace should appear in your LangSmith project within seconds
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that ferries traces from the route to the chat UI."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/migrations/index.mdx

@@ -0,0 +1,50 @@
+---
+title: Migration Guides
+description: Upgrade assistant-ui versions and migrate deprecated APIs and integrations.
+---
+
+Use these guides when upgrading assistant-ui or moving from APIs that have been deprecated or replaced.
+
+## Version upgrades
+
+<Cards>
+  <Card title="Migration to v0.14" href="/docs/migrations/v0-14">
+    Replace APIs removed after v0.11 and v0.12, and migrate primitive
+    `components` props to children render functions.
+  </Card>
+  <Card title="Migration to v0.12" href="/docs/migrations/v0-12">
+    Move from individual context hooks to the unified state API.
+  </Card>
+  <Card title="Migration to v0.11" href="/docs/migrations/v0-11">
+    Update code affected by the `ContentPart` to `MessagePart` rename.
+  </Card>
+</Cards>
+
+## APIs and integrations
+
+<Cards>
+  <Card title="Migrating Tools to Toolkits" href="/docs/migrations/toolkit-tools">
+    Move legacy tool and tool UI registrations to the toolkit API.
+  </Card>
+  <Card
+    title="Migrating to react-langgraph v0.7"
+    href="/docs/migrations/react-langgraph-v0-7"
+  >
+    Upgrade to the simplified LangGraph integration API.
+  </Card>
+  <Card
+    title="Using old React versions"
+    href="/docs/migrations/react-compatibility"
+  >
+    Review compatibility notes for React 18 and React 19.
+  </Card>
+</Cards>
+
+## Stability
+
+<Cards>
+  <Card title="Deprecation Policy" href="/docs/migrations/deprecation-policy">
+    Review stability guarantees and deprecation timelines for assistant-ui
+    features.
+  </Card>
+</Cards>

package/.docs/raw/docs/migrations/react-langgraph-v0-7.mdx

@@ -323,6 +323,6 @@ export function Provider({ children }) {
 ## Need Help?
 
 If you encounter issues during migration:
-1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph)
+1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph/overview)
 2. Review the [example implementation](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)
-3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)
+3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)

package/.docs/raw/docs/migrations/toolkit-tools.mdx

@@ -32,7 +32,7 @@ const WeatherTool = makeAssistantTool({
 });
 
 export function App() {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime();
 
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -80,7 +80,7 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import toolkit from "./toolkit";
 
 export function App() {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime();
   const aui = useAui({
     tools: Tools({ toolkit }),
   });
@@ -93,6 +93,8 @@ export function App() {
 }
 ```
 
+`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
+
 ## Mechanical Steps
 
 1. Create a `Toolkit` object.

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

@@ -5,6 +5,8 @@ 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 {
   ChainOfThoughtPrimitive as ChainOfThoughtPrimitiveDocs,
   MessagePrimitive as MessagePrimitiveDocs,
@@ -18,7 +20,10 @@ For new grouped reasoning/tool-call UI, use `MessagePrimitive.GroupedParts`. `Ch
 
 <Tabs items={["Preview", "Code"]}>
   <Tab>
-    <ChainOfThoughtPrimitiveSample />
+    <Flavored
+      base={<ChainOfThoughtPrimitiveSample />}
+      radix={<ChainOfThoughtPrimitiveSampleRadix />}
+    />
   </Tab>
   <Tab>
 ```tsx

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

@@ -165,6 +165,22 @@ Form container for message composition. Renders a `<form>` element unless `asChi
 </ComposerPrimitive.Root>
 ```
 
+#### Compact Mode
+
+Pass `compact` to opt into compact detection. While the input holds at most a single line of text and the composer has no attachments, quote, queued messages, or active dictation, the root renders a `data-compact` attribute. The prop only exposes this attribute for styling — it does not change the layout by itself. Target it with CSS to collapse the composer into a single row:
+
+```tsx
+<ComposerPrimitive.Root
+  compact
+  className="group/composer flex flex-col data-[compact]:flex-row data-[compact]:items-center"
+>
+  <ComposerPrimitive.Input placeholder="Ask anything..." />
+  <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+</ComposerPrimitive.Root>
+```
+
+Once the text wraps onto a second line, the composer expands and stays expanded until the input is cleared, so the layout doesn't oscillate at the wrap boundary.
+
 ### Input
 
 Text input with keyboard shortcuts. Renders a `<textarea>` element unless `asChild` is set.

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

@@ -63,6 +63,31 @@ The toolbar only appears when the selection is entirely within a single message.
 
 `Root` returns `null` when there is no valid selection (collapsed selection, empty text, or no single-message match).
 
+### Quote Regions
+
+By default, any selected text inside a message can be quoted. For rich messages with tool cards, attachments, or custom controls, add `data-aui-quote-selectable` to the element that contains the message text. Once a message has a quote-selectable region, selections must stay inside the same marked region for the toolbar to appear.
+
+```tsx
+<MessagePrimitive.Root>
+  <div data-aui-quote-selectable="">
+    <MessagePrimitive.Parts />
+  </div>
+  <ToolCard />
+</MessagePrimitive.Root>
+```
+
+Set `data-aui-quote-selectable="false"` to exclude an element instead: on the message root it disables quoting for the entire message, and inside a quotable region it carves that subtree out. The nearest marker wins, and any value other than `"false"` (including empty) marks a quotable region.
+
+Apps know the message role at render time, so a role gate is a conditional attribute:
+
+```tsx
+const UserMessage = () => (
+  <MessagePrimitive.Root data-aui-quote-selectable="false">
+    <MessagePrimitive.Parts />
+  </MessagePrimitive.Root>
+);
+```
+
 ### Quote Action
 
 The `Quote` button does two things on click:

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

@@ -38,12 +38,12 @@ function MyThreadList() {
 
 function ThreadListItem() {
   return (
-    <ThreadListItemPrimitive.Root className="group flex h-9 items-center rounded-lg hover:bg-muted data-active:bg-muted">
-      <ThreadListItemPrimitive.Trigger className="flex-1 truncate px-3 text-sm">
+    <ThreadListItemPrimitive.Root className="group relative flex h-9 items-center rounded-lg hover:bg-muted data-active:bg-muted has-focus-visible:bg-muted">
+      <ThreadListItemPrimitive.Trigger className="min-w-0 flex-1 truncate px-3 text-sm outline-none">
         <ThreadListItemPrimitive.Title fallback="New Chat" />
       </ThreadListItemPrimitive.Trigger>
-      <ThreadListItemMorePrimitive.Root>
-        <ThreadListItemMorePrimitive.Trigger className="mr-2 size-7 rounded-md opacity-0 group-hover:opacity-100">
+      <ThreadListItemMorePrimitive.Root sharedFocusGroup>
+        <ThreadListItemMorePrimitive.Trigger className="absolute end-1.5 top-1/2 size-7 -translate-y-1/2 rounded-md opacity-0 group-hover:opacity-100 group-has-focus-visible:opacity-100 data-[state=open]:opacity-100">
           <MoreHorizontalIcon className="size-4" />
         </ThreadListItemMorePrimitive.Trigger>
         <ThreadListItemMorePrimitive.Content className="rounded-md border bg-popover p-1 shadow-md">
@@ -118,6 +118,21 @@ Both `ThreadListPrimitive.New` and `ThreadListItemPrimitive.Root` get a `data-ac
 
 The `New` button gets `data-active` when the user is on a fresh, unsaved thread.
 
+### Keyboard Navigation
+
+Every item stays a native Tab stop, and arrow keys are layered on top. Up/Down move between items and Right focuses an item's `More` button (Left/Right are mirrored in RTL). This is built into the primitives — no prop is required.
+
+To fold the `More` menu into the same navigation, opt it in with `sharedFocusGroup`:
+
+```tsx
+<ThreadListItemMorePrimitive.Root sharedFocusGroup>
+  {/* Right opens the menu from the trigger; Left/Escape close it and
+      return focus to the trigger, keeping the highlight continuous. */}
+</ThreadListItemMorePrimitive.Root>
+```
+
+`sharedFocusGroup` joins the menu to the list's focus group, so its trigger and the open menu act as one keyboard-navigable unit: Right opens it and Left/Escape close it, synchronously restoring focus to the trigger so a `group-has-focus-visible` highlight never flickers. Enabling it forces the menu non-modal, because a focus trap and a shared focus group are mutually exclusive — the trap keeps focus inside the menu, the shared group lets it move out across the boundary. Without `sharedFocusGroup` the menu keeps its standard Radix `DropdownMenu` keyboard behavior (modal by default), so menus you already render are unchanged. Our assistant-ui [thread-list](/docs/ui/thread-list) registry component sets `sharedFocusGroup` for you.
+
 ### Items Iterator
 
 `ThreadListPrimitive.Items` now prefers a children render function, similar to `ThreadPrimitive.Messages`:
@@ -168,6 +183,15 @@ The canonical pattern composes `ThreadListItemPrimitive.Archive asChild` with `T
 
 `Archive` provides the click handler and disabled logic. `Item` provides the menu item behavior and styling. `asChild` merges them into a single element.
 
+## Accessibility
+
+The thread list leans on native button semantics and Radix's `DropdownMenu`; the arrow-key navigation is layered on top as a convenience, not a requirement.
+
+- Each `ThreadListItemPrimitive.Trigger` is a native `<button>` and its own Tab stop, so the whole list is reachable with <Kbd>Tab</Kbd> alone. The arrow keys (see [Keyboard Navigation](#keyboard-navigation)) speed traversal up, but nothing depends on them.
+- The item representing the current thread sets `aria-current="true"` (alongside `data-active`) on `ThreadListItemPrimitive.Root`, so assistive tech announces which conversation is open.
+- The `More` trigger exposes `aria-haspopup="menu"`, and its panel is a Radix `role="menu"` with `role="menuitem"` children, so screen readers announce it as a menu and the arrow keys cycle its items.
+- With `sharedFocusGroup`, the `More` menu is non-modal and joins the list's focus group: opening and closing it move focus synchronously between the trigger and the menu, so keyboard focus is never dropped and the `group-has-focus-visible` highlight never flickers. Without it, the menu keeps Radix's default modal focus trap.
+
 ## Parts
 
 ### ThreadListPrimitive
@@ -319,10 +343,10 @@ Button that deletes the current thread item. Renders a `<button>` element unless
 
 #### Root
 
-Root container for the overflow menu primitives.
+Root container for the overflow menu primitives. Pass `sharedFocusGroup` to fold the menu into the list's arrow-key navigation (see [Keyboard Navigation](#keyboard-navigation)); doing so forces it non-modal. Without it the menu honors the `modal` prop, defaulting to modal like Radix's `DropdownMenu`.
 
 ```tsx
-<ThreadListItemMorePrimitive.Root>
+<ThreadListItemMorePrimitive.Root sharedFocusGroup>
   <ThreadListItemMorePrimitive.Trigger>More</ThreadListItemMorePrimitive.Trigger>
 </ThreadListItemMorePrimitive.Root>
 ```

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

@@ -362,6 +362,29 @@ Renders message content parts using render-prop functions instead of the compone
 | `renderFile` | `(props: { part, index }) => ReactElement` | Renderer for file parts |
 | `renderData` | `(props: { part, index }) => ReactElement` | Fallback renderer for data parts not handled by registered data UIs |
 
+#### Rendering Markdown
+
+`MessagePrimitive.Content` renders text parts with React Native's `<Text>` by default, so markdown syntax is displayed as plain text. To render markdown, install a React Native markdown renderer and pass it through `renderText`:
+
+<InstallCommand npm={["react-native-markdown-display"]} />
+
+```tsx
+import Markdown from "react-native-markdown-display";
+import { MessagePrimitive } from "@assistant-ui/react-native";
+
+const AssistantMessage = () => {
+  return (
+    <MessagePrimitive.Root>
+      <MessagePrimitive.Content
+        renderText={({ part }) => (
+          <Markdown>{part.text}</Markdown>
+        )}
+      />
+    </MessagePrimitive.Root>
+  );
+};
+```
+
 ### MessagePrimitive.Parts
 
 Renders message content parts via a `components` prop. Tool call and data parts automatically render registered toolkit renderers and data UIs (via `useAssistantDataUI`), falling back to components provided here. A default `Text` component using React Native's `<Text>` is provided out of the box.

package/.docs/raw/docs/runtimes/a2a/quickstart.mdx

@@ -3,7 +3,7 @@ title: Quickstart
 description: Minimal runtime and Thread setup against an A2A server.
 ---
 
-Three steps to a working chat against an A2A server. Assumes you have already installed the package and have an A2A v1.0 server reachable; if not, start at [overview](/docs/runtimes/a2a).
+Three steps to a working chat against an A2A server. Assumes you have already installed the package and have an A2A v1.0 server reachable; if not, start at [overview](/docs/runtimes/a2a/overview).
 
 <Steps>
 <Step>

package/.docs/raw/docs/runtimes/ag-ui/agent-state.mdx

@@ -0,0 +1,124 @@
+---
+title: Agent state
+description: Read and optimistically update agent-owned state with useAgUiState and useAgUiSetState over AG-UI.
+---
+
+`useAgUiState` mirrors the state your AG-UI agent owns. It updates live while the agent runs. `useAgUiSetState` lets you apply optimistic local updates that are sent with the next run.
+
+## Basic usage
+
+```tsx
+import { useAgUiState, useAgUiSetState } from "@assistant-ui/react-ag-ui";
+import { useAuiState } from "@assistant-ui/react";
+
+type ResearchState = {
+  topic: string;
+  sources: string[];
+};
+
+const state = useAgUiState<ResearchState>();
+// state: ResearchState | undefined  (latest agent state; updates live while the agent runs)
+
+const setState = useAgUiSetState<ResearchState>();
+// setState(next | (prev) => next)   (optimistic local update; sent with the NEXT run)
+
+const isRunning = useAuiState((s) => s.thread.isRunning);
+// isRunning: boolean                (whether the thread is currently running)
+```
+
+## Example
+
+Render agent state beside the chat and push an optimistic update from a control in your UI:
+
+```tsx
+"use client";
+
+import { useAgUiState, useAgUiSetState } from "@assistant-ui/react-ag-ui";
+import { useAuiState } from "@assistant-ui/react";
+import { Thread } from "@/components/assistant-ui/thread";
+
+type ResearchState = {
+  topic: string;
+  sources: string[];
+};
+
+export function ResearchAssistant() {
+  const state = useAgUiState<ResearchState>();
+  const setState = useAgUiSetState<ResearchState>();
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+
+  return (
+    <div className="flex h-full">
+      <aside className="w-72 border-r p-4">
+        <h2>Research state</h2>
+        {state ? (
+          <ul>
+            <li>Topic: {state.topic}</li>
+            <li>Sources: {state.sources.join(", ") || "none"}</li>
+          </ul>
+        ) : (
+          <p>No agent state yet.</p>
+        )}
+        <button
+          type="button"
+          disabled={isRunning}
+          onClick={() =>
+            setState((prev) => ({
+              topic: prev?.topic ?? "market analysis",
+              sources: [...(prev?.sources ?? []), "sec-filings"],
+            }))
+          }
+        >
+          Prefer SEC filings
+        </button>
+        {isRunning && <p>Agent is running…</p>}
+      </aside>
+      <main className="flex-1">
+        <Thread />
+      </main>
+    </div>
+  );
+}
+```
+
+The panel re-renders as `STATE_SNAPSHOT` and `STATE_DELTA` events arrive. The button updates the local snapshot immediately; that value is included as the `state` field of the next run input.
+
+## How state is synced
+
+The AG-UI protocol delivers agent state on the wire:
+
+- `STATE_SNAPSHOT` replaces the full client-side snapshot.
+- `STATE_DELTA` applies a JSON Patch to the current snapshot.
+
+The runtime applies both client-side, so `useAgUiState` always reflects the latest merged snapshot. Calling the setter from `useAgUiSetState` updates that same local snapshot. On the next run, the runtime automatically includes it as the `state` field of the run input.
+
+This works with any AG-UI agent (Mastra, Pydantic AI, CrewAI, LangGraph via AG-UI adapters, and other AG-UI-compliant servers).
+
+## Write-back timing
+
+`useAgUiSetState` is optimistic and local first. The value reaches the agent only when the next run starts. It is not a live channel into a run that is already in progress. Use it to stage preferences, filters, or other agent-owned fields that the next turn should see.
+
+## Relationship to other state
+
+Keep the three state layers distinct:
+
+- **Your app state** stays yours (React state, URL, a store). assistant-ui does not own it.
+- **`useAuiState`** reads assistant-ui's client state (messages, composer, thread status).
+- **`useAgUiState` / `useAgUiSetState`** mirror state the **agent** owns, synced over the AG-UI wire via snapshots and deltas.
+
+Use `useAgUiState` and `useAgUiSetState` for fields your agent maintains as shared state on the protocol. Use `useAuiState` for UI that depends on the chat thread itself. Use your own state for everything else.
+
+## Next
+
+<Cards>
+  <Card
+    title="Runtime options"
+    description="useAgUiRuntime options, adapters, supported events."
+    href="/docs/runtimes/ag-ui/runtime-options"
+  />
+  <Card
+    title="Quickstart"
+    description="Minimal HttpAgent + useAgUiRuntime setup."
+    href="/docs/runtimes/ag-ui/quickstart"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/ag-ui/quickstart.mdx

@@ -3,7 +3,7 @@ title: Quickstart
 description: Minimal HttpAgent + useAgUiRuntime setup against an AG-UI server.
 ---
 
-Three steps to a working chat against an AG-UI agent. Assumes you have already installed the package and have an AG-UI server reachable; if not, start at [overview](/docs/runtimes/ag-ui).
+Three steps to a working chat against an AG-UI agent. Assumes you have already installed the package and have an AG-UI server reachable; if not, start at [overview](/docs/runtimes/ag-ui/overview).
 
 <Steps>
 <Step>

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

@@ -14,6 +14,7 @@ Reference for the runtime's API surface. Start with [quickstart](/docs/runtimes/
 | `agent` | `HttpAgent` | An AG-UI client agent (from `@ag-ui/client`). Required. |
 | `logger` | `Partial<Logger>` | Optional logger overrides. The runtime logs event-parser warnings and run lifecycle events. |
 | `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. |
 | `adapters` | `UseAgUiRuntimeAdapters` | Standard adapter slots (see below). |
@@ -70,6 +71,8 @@ time, the same way a live run never stores them.
 
 An assistant message whose tool call has no matching tool result is reconstructed with `requires-action` status, the same status the runtime derives for a pending tool call, so a reloaded human-in-the-loop call (for example an `ask_user` tool) is actionable rather than stuck. This matches how every other external-store runtime surfaces a pending tool call on reload. The AG-UI wire snapshot carries no run outcome, so a tool call that a successful run intentionally left without a result is also surfaced as actionable.
 
+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.
+
 ## Thread list (experimental)
 
 <Callout type="warn">
@@ -135,7 +138,9 @@ await runtime.unstable_submitInterruptResponses(
 
 ### Steering away from an interrupt
 
-When the user ignores the interrupt UI and just sends a new message, use the `useAgUiSteerAway` hook. Every open interrupt defaults to `status: "cancelled"`, the new message is appended, and the run resumes with `resume: ResumeEntry[]` on the wire. With no pending interrupts it behaves like a normal append.
+When the user ignores the interrupt UI and just sends a new message, use the `useAgUiSteerAway` hook. Every open interrupt defaults to `status: "cancelled"`, the new message is appended, and the run resumes with `resume: ResumeEntry[]` on the wire.
+
+The same hook also steers away from pending client-side tool calls. When the head assistant message is in `requires-action` with `reason: "tool-calls"` (frontend tools awaiting a result) and the user sends a new message, every unresolved tool call is cancelled with an error result, the message is completed, and a single fresh run starts with those cancellations in its history. Passing `responses` in this case throws, since responses only address interrupts. With nothing pending, `steerAway` behaves like a normal append.
 
 ```tsx
 const steerAway = useAgUiSteerAway();
@@ -152,6 +157,12 @@ await steerAway("continue without the file", [
 ]);
 ```
 
+### Auto-cancelling pending tool calls
+
+By default the runtime does the tool-call half of this automatically: when client-side tool calls are still unresolved and the user sends a new message, edits an earlier one, or reloads, every unresolved tool call receives the same cancellation error result, the assistant message is completed, and the run proceeds with those cancellations in its history. Set `autoCancelPendingToolCalls: false` to opt out, in which case pending tool calls stay unresolved on a plain send and [steering away](#steering-away-from-an-interrupt) remains the explicit way to cancel them.
+
+Pending interrupts are never auto-cancelled: sending while an interrupt is open still throws, and the interrupt must be answered with `useAgUiSubmitInterruptResponses` or discarded with `useAgUiSteerAway`.
+
 ## Supported events
 
 The runtime parses the AG-UI event stream and maps each event type to assistant-ui state.
@@ -199,7 +210,7 @@ The runtime parses the AG-UI event stream and maps each event type to assistant-
     icon={<AguiIcon width={20} height={20} />}
     title="AG-UI overview"
     description="What AG-UI is and when to pick it."
-    href="/docs/runtimes/ag-ui"
+    href="/docs/runtimes/ag-ui/overview"
   />
   <Card
     title="Quickstart"