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

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

@@ -48,17 +48,17 @@ npm init -y
 <PlatformTabs>
 <Tab value="React">
 
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod"]} />
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod"]} />
 
 </Tab>
 <Tab value="React Native">
 
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod"]} />
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod"]} />
 
 </Tab>
 <Tab value="React Ink">
 
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod", "ink", "react"]} />
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod", "ink", "react"]} />
 
 </Tab>
 </PlatformTabs>
@@ -122,7 +122,7 @@ export async function POST(req: Request) {
 
 import { Thread } from "@/components/assistant-ui/thread";
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 
 export default function Home() {
   const runtime = useChatRuntime();
@@ -144,7 +144,7 @@ import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
 import {
   AssistantChatTransport,
   useChatRuntime,
-} from "@assistant-ui/react-ai-sdk";
+} from "@assistant-ui/ai-sdk";
 import { View } from "react-native";
 import { Thread } from "@/components/assistant-ui/thread";
 
@@ -174,7 +174,7 @@ import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
 import {
   AssistantChatTransport,
   useChatRuntime,
-} from "@assistant-ui/react-ai-sdk";
+} from "@assistant-ui/ai-sdk";
 import { Box } from "ink";
 import { Thread } from "./components/thread.js";
 
@@ -231,7 +231,7 @@ Follow the [Ink setup](/docs/ink) to add a terminal Thread, composer, and suppor
 import { openai } from "@ai-sdk/openai";
 import { streamText, convertToModelMessages, zodSchema, createUIMessageStreamResponse, toUIMessageStream } from "ai";
 import type { UIMessage } from "ai";
-import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import { frontendTools } from "@assistant-ui/ai-sdk";
 
 export async function POST(req: Request) {
   const {
@@ -341,7 +341,7 @@ import { useChat } from "@ai-sdk/react";
 import {
   AssistantRuntimeProvider,
   useAISDKRuntime,
-} from "@assistant-ui/react-ai-sdk";
+} from "@assistant-ui/ai-sdk";
 import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
 import { Thread } from "@/components/assistant-ui/thread";
 
@@ -372,7 +372,7 @@ import {
   defineToolkit,
   Tools,
 } from "@assistant-ui/react";
-import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
+import { useAISDKRuntime } from "@assistant-ui/ai-sdk";
 import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
 import { Thread } from "@/components/assistant-ui/thread";
 
@@ -432,7 +432,7 @@ import {
   createUIMessageStreamResponse,
   toUIMessageStream,
 } from "ai";
-import { injectQuoteContext } from "@assistant-ui/react-ai-sdk";
+import { injectQuoteContext } from "@assistant-ui/ai-sdk";
 import { openai } from "@ai-sdk/openai";
 
 export async function POST(req: Request) {
@@ -455,7 +455,7 @@ export async function POST(req: Request) {
 
 ```ts title="@/app/api/chat/route.ts"
 import { streamText, convertToModelMessages, createUIMessageStreamResponse, toUIMessageStream } from "ai";
-import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import { frontendTools } from "@assistant-ui/ai-sdk";
 
 export async function POST(req: Request) {
   const { messages, tools, config } = await req.json();
@@ -484,7 +484,7 @@ export async function POST(req: Request) {
 ```tsx title="@/components/TokenCounter.tsx"
 "use client";
 
-import { useThreadTokenUsage } from "@assistant-ui/react-ai-sdk";
+import { useThreadTokenUsage } from "@assistant-ui/ai-sdk";
 
 export function TokenCounter() {
   const usage = useThreadTokenUsage();
@@ -539,7 +539,7 @@ For server-side cloud persistence with zero adapter code, see the [AssistantClou
 ```tsx
 "use client";
 
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 import type { ThreadHistoryAdapter } from "@assistant-ui/react";
 
 const historyAdapter: ThreadHistoryAdapter = {
@@ -585,7 +585,7 @@ Each persisted row follows `{ id, parent_id, format, content }`. `fmt.encode` pr
 import {
   useChatRuntime,
   AssistantChatTransport,
-} from "@assistant-ui/react-ai-sdk";
+} from "@assistant-ui/ai-sdk";
 
 const runtime = useChatRuntime({
   transport: new AssistantChatTransport({ api: "/my-custom-api/chat" }),
@@ -644,13 +644,28 @@ const runtime = useChatRuntime({
 
 When omitted, `resumeRun` throws `"Runtime does not support resuming runs."`. For streams that should survive a page reload without a custom channel, use the built-in transport-level path instead: see [Resumable streams](/docs/guides/resumable-streams), which reconnects automatically on mount and reports failures via `onResumeError`.
 
+### messageRepository
+
+Import a branch-aware AI SDK message tree once, and only when `useChat` is empty. After that seed, live updates come only from `useChat`. Clearing the chat or passing a new object identity does not reload the tree. Persisted threads that already go through `adapters.history` do not need this.
+
+```tsx
+const runtime = useChatRuntime({
+  messageRepository: storedTree,
+  unstable_onBranchChange: ({ headId }) => {
+    saveSelectedBranch(headId);
+  },
+});
+```
+
+`unstable_onBranchChange` fires after an explicit `switchToBranch` (for example a BranchPicker click). It complements `setMessages` and does not enable switching by itself. The callback is unstable and may change without notice.
+
 ## Advanced: useAISDKRuntime
 
 When you need direct access to the `useChat` instance (e.g. to share it with non-assistant-ui code), drop down to `useAISDKRuntime`:
 
 ```tsx
 import { useChat } from "@ai-sdk/react";
-import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
+import { useAISDKRuntime } from "@assistant-ui/ai-sdk";
 
 const chat = useChat();
 const runtime = useAISDKRuntime(chat);
@@ -658,7 +673,7 @@ const runtime = useAISDKRuntime(chat);
 
 `useAISDKRuntime` does not provide `cloud` or the higher-level adapter slots; those are part of `useChatRuntime`. If you need both your own `useChat` access AND cloud thread support, you generally want `useChatRuntime` and to read the chat state through assistant-ui hooks instead.
 
-`useAISDKRuntime` accepts `joinStrategy` and `onResume` (see [Runtime options](#runtime-options)) plus one option of its own, `cancelPendingToolCallsOnSend`:
+`useAISDKRuntime` accepts `joinStrategy`, `onResume`, `messageRepository`, and `unstable_onBranchChange` (see [Runtime options](#runtime-options)) plus one option of its own, `cancelPendingToolCallsOnSend`:
 
 ```tsx
 const runtime = useAISDKRuntime(chat, {

package/.docs/raw/docs/runtimes/claude-managed-agents.mdx

@@ -0,0 +1,118 @@
+---
+title: Claude Managed Agents
+description: Connect Anthropic's Managed Agents sessions to assistant-ui with the external store runtime, folding the session event log into messages, rendering approval gates, and using sessions as the thread list.
+---
+
+[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) is Anthropic's hosted agent platform: Anthropic runs the agent loop and provisions a sandboxed container per session, and your client drives the session over an event stream. A session holds the entire conversation server-side as a durable event log, streams every step (text, tool calls, approval stops, status) as typed events, and accepts user messages and tool confirmations back.
+
+That shape maps directly onto two assistant-ui primitives, with no adapter package in between:
+
+- [`useExternalStoreRuntime`](/docs/runtimes/custom/external-store) renders messages you derive from the session's event log. The log is the single source of truth, so replaying a stored session and tailing a live one run through the same pure function and can never disagree.
+- [`useRemoteThreadListRuntime`](/docs/api-reference/hooks/runtimes#useremotethreadlistruntime) turns the session list into the thread sidebar. A thread is a session; there is no conversations table anywhere in the app.
+
+Anthropic ships an official reference implementation of this integration: the [Claude Managed Agents quickstart](https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/assistant-ui) is a complete Next.js app (composer, thread, sidebar, tool cards, approval gate) built exactly this way. This page teaches the pattern; the quickstart is the runnable proof.
+
+<Callout type="info">
+Managed Agents is a beta API (`managed-agents-2026-04-01`; the SDK sets the header automatically). The quickstart declares `@anthropic-ai/sdk` `^0.113.0` (the session event helpers and token previews need 0.109.0 or later), and `@assistant-ui/react` 0.14.27 or later for the toolkit API and the approval gate on the external store runtime.
+</Callout>
+
+## The event-to-message mapping
+
+Everything the session emits arrives as a typed event. The integration is one pure fold from the event array to assistant-ui's message model:
+
+| Managed Agents event | assistant-ui |
+| --- | --- |
+| `user.message` | A user message |
+| `agent.message` | Assistant text (buffered, authoritative) |
+| `event_start` / `event_delta` | The same text, streamed early as token previews |
+| `agent.thinking` | A reasoning part (progress signal only; the API sends no reasoning text) |
+| `agent.tool_use` / `agent.mcp_tool_use` / `agent.custom_tool_use` | A tool-call part; the `toolCallId` is the event id |
+| `agent.tool_result` (and mcp / custom variants) | That part's result |
+| `session.status_idle` with `stop_reason: requires_action` | `requires-action` message status, plus an approval on each blocked tool part |
+| `user.tool_confirmation` | The approval, settled (allowed or denied) |
+| `session.status_running` / `status_idle` | Whether the turn is live (`isRunning`) |
+| `session.error` | An error status on the message, or a retry banner |
+
+Because the fold is pure, opening an old chat replays `sessions.events.list()` through it, and a live chat feeds the SSE tail through it, and the two paths cannot render differently. Approvals, denials, and charts all come back after a reload because they are in the log, not in browser state.
+
+The runtime wiring is a structural subset of `ThreadMessageLike`, handed to the external store as-is:
+
+```tsx
+const runtime = useExternalStoreRuntime<ThreadMessageLike>({
+  messages: snapshot.messages,
+  convertMessage: (m) => m,
+  isRunning: isBusy(snapshot),
+
+  onNew: async (message) => {
+    const id = await ensureSession();
+    await sendMessage(id, textOf(message));
+  },
+
+  // The Stop button becomes a real server-side interrupt.
+  onCancel: async () => controller.interrupt(),
+
+  // The Allow / Deny click on a gated tool call. approvalId is the
+  // tool_use event id from session.status_idle { requires_action }.
+  onRespondToToolApproval: async ({ approvalId, approved, reason }) => {
+    controller.respondToApproval(approvalId, approved, reason);
+  },
+});
+```
+
+## Sessions are the thread list
+
+The sidebar is a `RemoteThreadListAdapter` over the Managed Agents session API. Thread id and session id are the same string, so nothing maps between the two worlds:
+
+| Adapter method | Managed Agents call |
+| --- | --- |
+| `list` | `sessions.list()`, filtered to the sessions this app created (a `metadata` tag) |
+| `initialize` | `sessions.create()`, invoked by assistant-ui on the first message of a new chat |
+| `rename` | `sessions.update({ title })` |
+| `archive` | `sessions.archive()` |
+| `unarchive` | Throws. Managed Agents sessions cannot be unarchived, and switching to an archived thread auto-unarchives by default, so do not render archived sessions as switchable (the quickstart's ownership gate rejects archived ids outright) |
+| `delete` | `sessions.delete()` |
+| `fetch` | `sessions.retrieve()` |
+| `generateTitle` | Reads the title back after the server retitles the session from the first message, so the sidebar row updates without a second model call |
+
+A brand-new chat has no session until the first send: the composer works immediately, and `initialize()` creates the session lazily when the first message (or first attachment upload) needs one. Kill the server, restart, reload, and every conversation comes back, because none of it ever lived in the app.
+
+## The approval gate
+
+Managed Agents supports per-tool [permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies). A tool configured as `always_ask` (the quickstart gates `bash` this way) does not run when the agent reaches for it. The session emits the `agent.tool_use` event, then parks:
+
+```json
+{ "type": "session.status_idle", "stop_reason": { "type": "requires_action", "event_ids": ["sevt_..."] } }
+```
+
+The fold stamps an approval onto that tool part and sets the message status to `requires-action`, which is everything assistant-ui needs to render Allow and Deny on the tool card. The click flows back through `onRespondToToolApproval` as a `user.tool_confirmation` event:
+
+```json
+{ "type": "user.tool_confirmation", "tool_use_id": "sevt_...", "result": "deny", "deny_message": "Not on this box." }
+```
+
+Two wire details matter. The `tool_use_id` is the tool-use event id, not an Anthropic `toolu_` id. And a denial reaches the agent as the tool's result, so it adjusts course instead of retrying the same command.
+
+Custom client-executed tools ride the same `requires_action` stop but take a `user.custom_tool_result` instead of a confirmation; sending a confirmation for one is a 400. The quickstart's inline chart tool is the worked example: the session parks, the card renders the chart from the tool's input, and the client answers so the agent continues.
+
+## Token streaming
+
+By default assistant text arrives as whole `agent.message` events when a model request finishes. Opting the stream into `event_deltas: ["agent.message", "agent.thinking"]` adds token previews: an `event_start` announces the upcoming event, `event_delta` fragments stream the text, and the buffered event lands last as the authoritative record. Concatenating a preview's deltas in arrival order yields a prefix of the final text, but under load the server may shed the remaining deltas for an event, so the prefix is not necessarily the whole message. The fold therefore appends fragments for display and discards the accumulated preview when the buffered event arrives; never treat a preview as final. When a turn errors or is interrupted, the buffered event may never arrive at all, but `span.model_request_end` still does, so close any unreconciled preview when you see it.
+
+Previews are best-effort and gated per organization. Build against the buffered events and treat deltas as an enhancement: an org without the streaming gate runs the identical code path with replies arriving whole.
+
+## Security boundary
+
+The Anthropic API key stays server-side; the browser talks only to your own route handlers, which relay to Managed Agents. Because a session id arrives from the browser and becomes an API path parameter, validate ownership on every route: the id must resolve, belong to your agent, and carry your app's metadata tag before any read or write. The API key can see the whole workspace; that gate is what keeps a guessed id from reading it. The quickstart's [`ownedSession()`](https://github.com/anthropics/claude-quickstarts/blob/main/managed-agents/assistant-ui/lib/owned-session.ts) is the reference shape.
+
+## Run the reference
+
+```bash
+git clone https://github.com/anthropics/claude-quickstarts
+cd claude-quickstarts/managed-agents/assistant-ui
+npm install
+cp .env.example .env   # add ANTHROPIC_API_KEY, or `ant auth login` once
+npm run setup          # one-time: creates the agent + environment, paste the IDs into .env
+npm run dev            # drop sample_data/sales.csv into the chat
+```
+
+The quickstart's [README](https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/assistant-ui#readme) walks through every file: the reducer, the session controller, the thread list adapter, the tool cards, and the attachment adapter that uploads composer files into the session sandbox. For the platform itself, start with Anthropic's [Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview) and [events reference](https://platform.claude.com/docs/en/managed-agents/events-and-streaming).

package/.docs/raw/docs/runtimes/concepts/adapters.mdx

@@ -21,7 +21,7 @@ const runtime = useChatRuntime({ adapters: { attachments, history } });
 
 ## Support matrix
 
-| Adapter | LocalRuntime | ExternalStoreRuntime | DataStream | AssistantTransport | react-ai-sdk | react-langgraph | react-langchain | react-google-adk | react-a2a | react-ag-ui | react-opencode |
+| Adapter | LocalRuntime | ExternalStoreRuntime | DataStream | AssistantTransport | ai-sdk | react-langgraph | react-langchain | react-google-adk | react-a2a | react-ag-ui | react-opencode |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | Attachments | Yes | Yes | Yes | Yes | Yes | (via thread state) | (via thread state) | Yes | Yes | Yes | (no) |
 | Speech | Yes | Yes | Yes | (no) | Yes | Yes | Yes | Yes | Yes | Yes | (no) |
@@ -173,7 +173,7 @@ const feedbackAdapter: FeedbackAdapter = {
 
 ## History adapter
 
-Per-thread message persistence. Used by `LocalRuntime` and adapters built on it (`react-ai-sdk`, `react-google-adk`, `react-a2a`, `useDataStreamRuntime`).
+Per-thread message persistence. Used by `LocalRuntime` and adapters built on it (`ai-sdk`, `react-google-adk`, `react-a2a`, `useDataStreamRuntime`).
 
 `ExternalStoreRuntime` does not use a history adapter directly, since you already own the message array. Persist via your store instead. `react-langgraph` and `react-langchain` source persistence from server-side thread state, exposed through their `load` callbacks.
 
@@ -196,7 +196,7 @@ type ThreadHistoryAdapter = {
 `load` runs when a thread opens. `append` runs after each message completes.
 
 <Callout type="info">
-`react-ai-sdk` requires `withFormat` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime in the AI SDK path. See the [AI SDK history docs](/docs/runtimes/ai-sdk/v7) for the full pattern.
+`ai-sdk` requires `withFormat` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime in the AI SDK path. See the [AI SDK history docs](/docs/runtimes/ai-sdk/v7) for the full pattern.
 </Callout>
 
 ## Suggestion adapter

package/.docs/raw/docs/runtimes/concepts/architecture.mdx

@@ -10,7 +10,7 @@ assistant-ui exposes runtime integrations at three layers. Understanding which l
 <Flow.Root
   llm={`graph TD
     subgraph Framework["Framework adapters"]
-      A1[react-ai-sdk]
+      A1[ai-sdk]
       A2[react-langgraph]
       A3[react-langchain]
       A4[react-google-adk]
@@ -58,7 +58,7 @@ assistant-ui exposes runtime integrations at three layers. Understanding which l
       <Flow.Group flowId="adapters">
         <Flow.GroupLabel>Framework adapters</Flow.GroupLabel>
         <Flow.Row className="flex-wrap justify-start">
-          <Flow.Node>react-ai-sdk</Flow.Node>
+          <Flow.Node>ai-sdk</Flow.Node>
           <Flow.Node>react-langgraph</Flow.Node>
           <Flow.Node>react-langchain</Flow.Node>
           <Flow.Node>react-google-adk</Flow.Node>
@@ -118,7 +118,7 @@ The fastest path. Each adapter wraps one of the core or protocol layers and adds
 
 | Adapter | Layered on | Targets |
 | --- | --- | --- |
-| `react-ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v7 (`useChat`) |
+| `ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v7 (`useChat`) |
 | `react-langgraph` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/langgraph-sdk` |
 | `react-langchain` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/react`'s `useStream` |
 | `react-google-adk` | `ExternalStoreRuntime` | Google ADK JS or Python agents |

package/.docs/raw/docs/runtimes/concepts/stability.mdx

@@ -33,7 +33,8 @@ A non-exhaustive list of `unstable_` exports surfaced in the runtime docs.
 | `unstable_humanToolNames` | `@assistant-ui/react` | Tool names that pause the run until a result is added via `addResult`. Only available on LocalRuntime; not supported in DataStream. |
 | `unstable_threadListAdapter` | `@assistant-ui/react-langgraph` | LangGraph thread-list adapter slot on `useLangGraphRuntime`. |
 | `unstable_createLangGraphStream` | `@assistant-ui/react-langgraph` | End-to-end cancellation primitive. |
-| `unstable_Provider` | Various adapters | Thread-scoped provider on `RemoteThreadListAdapter`. Must render children synchronously. |
+| `unstable_Provider` | Various adapters | React-component face on `RemoteThreadListAdapter`. Must render children synchronously. `useRemoteThreadListRuntime` renders it when present; the `RemoteThreadList` store entry ignores it. |
+| `unstable_useAdapters` | Various adapters | Hook face on `RemoteThreadListAdapter`. The `RemoteThreadList` store entry calls it. `useRemoteThreadListRuntime` synthesizes a `RuntimeAdapterProvider` from it when `unstable_Provider` is omitted. |
 | `unstable_capabilities` | `ExternalStoreRuntime` | Toggle copy and other thread capabilities. |
 | `unstable_state`, `unstable_annotations`, `unstable_data` | Message metadata | Runtime-internal fields exposed for advanced use cases. |
 | `unstable_assistantMessageId`, `unstable_threadId`, `unstable_parentId`, `unstable_getMessage` | `ChatModelRunOptions` | Identifiers and accessors passed to your `ChatModelAdapter.run`. |

package/.docs/raw/docs/runtimes/concepts/threads.mdx

@@ -37,10 +37,11 @@ const cloud = new AssistantCloud({
 const runtime = useLocalRuntime(modelAdapter, { cloud });
 ```
 
-Framework adapters take `cloud` directly:
+Framework adapters take `cloud` directly. `AISDKThreads({ cloud })` is the store-entry list for `AuiConfig` hosts. It mounts only the visible thread, so a switch cancels an in-flight run and that exchange is not persisted.
 
 ```tsx
 const runtime = useChatRuntime({ cloud });
+const threads = AISDKThreads({ cloud });
 const runtime = useLangGraphRuntime({ cloud /* stream, load, ... */ });
 const runtime = useAdkRuntime({ cloud, stream });
 ```
@@ -49,9 +50,9 @@ See the [cloud documentation](/docs/cloud) for setup, auth, and self-host option
 
 ## RemoteThreadListRuntime (custom database)
 
-`useRemoteThreadListRuntime` lets you back the thread list with any database while keeping the per-thread runtime simple. You provide a `RemoteThreadListAdapter` describing how to list, create, rename, archive, and delete threads.
+`useRemoteThreadListRuntime` lets you back the thread list with any database while keeping the per-thread runtime simple. You provide a `RemoteThreadListAdapter` describing how to list, create, rename, archive, and delete threads. Keep that adapter reference stable across renders (module scope or `useMemo`). Replacing it reloads the list and drops cached threads that are not in the replacement page.
 
-Works with any `LocalRuntime`-based runtime, including framework adapters that build on it (`react-ai-sdk`, `react-google-adk`, `react-a2a`, `useDataStreamRuntime`).
+Works with any `LocalRuntime`-based runtime, including framework adapters that build on it (`ai-sdk`, `react-google-adk`, `react-a2a`, `useDataStreamRuntime`).
 
 ```tsx title="app/MyProvider.tsx"
 "use client";
@@ -130,44 +131,68 @@ export function MyProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### Persisting messages with `unstable_Provider`
+### Persisting messages
 
-`RemoteThreadListAdapter` only manages thread metadata. To persist messages within each thread, expose a thread-scoped history adapter via the optional `unstable_Provider`:
+`RemoteThreadListAdapter` only manages thread metadata. Per-thread history and attachments are a separate seam with two faces:
+
+- `unstable_useAdapters` is a hook. The `RemoteThreadList` store entry calls it inside the client tree, so any `createAssistantClient` host gets the same adapters as a React hook host. `useRemoteThreadListRuntime` also calls it when `unstable_Provider` is omitted.
+- `unstable_Provider` is a React component. `useRemoteThreadListRuntime` renders it when present. The store entry ignores it.
+
+On the store entry, wrap the thread factory with `withKey` so the thread remounts on a switch. History adapters load once per mount. An unkeyed factory keeps one instance, and the next thread's messages never appear.
+
+```tsx
+import { withKey } from "@assistant-ui/tap";
+import { RemoteThreadList } from "@assistant-ui/react";
+
+threads: RemoteThreadList({
+  adapter,
+  thread: (id) => withKey(id, MyThread({ threadId: id })),
+}),
+```
+
+Share one hook between both faces:
 
 ```tsx
 import {
   RuntimeAdapterProvider,
   useAui,
+  type RemoteThreadListAdapter,
   type ThreadHistoryAdapter,
 } from "@assistant-ui/react";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        const { remoteId } = aui.threadListItem.getState();
+        if (!remoteId) return { messages: [] };
+        const rows = await fetch(
+          `/api/threads/${remoteId}/messages`,
+        ).then((r) => r.json());
+        return { messages: rows.map(toThreadMessage) };
+      },
+      async append({ message, parentId }) {
+        const { remoteId } = await aui.threadListItem.initialize();
+        await fetch(`/api/threads/${remoteId}/messages`, {
+          method: "POST",
+          body: JSON.stringify({ message, parentId }),
+        });
+      },
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 const adapterWithHistory: RemoteThreadListAdapter = {
   // ...metadata methods above...
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          const { remoteId } = aui.threadListItem.getState();
-          if (!remoteId) return { messages: [] };
-          const rows = await fetch(
-            `/api/threads/${remoteId}/messages`,
-          ).then((r) => r.json());
-          return { messages: rows.map(toThreadMessage) };
-        },
-        async append({ message, parentId }) {
-          const { remoteId } = await aui.threadListItem.initialize();
-          await fetch(`/api/threads/${remoteId}/messages`, {
-            method: "POST",
-            body: JSON.stringify({ message, parentId }),
-          });
-        },
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -192,6 +217,15 @@ async append({ message, parentId }) {
 
 `initialize()` is safe to call multiple times. It always resolves to the same `remoteId` for the active thread.
 
+The same rule applies to a custom external store's dispatch. The runtime does not hold `onNew` or `onEdit` until the thread record exists (that would keep the user's message off screen for the whole roundtrip), so a handler that talks to a backend keyed by the remote identity must await `initialize()` itself:
+
+```ts
+onNew: async (message) => {
+  const { remoteId } = await aui.threadListItem.initialize();
+  await sendToBackend(remoteId, message);
+},
+```
+
 ### Reloading after async authentication
 
 If your adapter depends on a user that resolves asynchronously (oidc, `next-auth`, `better-auth`), the initial `list()` may run before the user is available. Call `aui.threads.reload()` after auth completes:
@@ -207,11 +241,11 @@ function ReloadOnAuth() {
 }
 ```
 
-`reload()` discards in-flight responses from superseded calls, so it is safe to invoke on every auth transition.
+`reload()` discards in-flight responses from superseded calls, so it is safe to invoke on every auth transition. On the `RemoteThreadList` store entry, a recreated adapter object is a no-op until you call `reload()`. `reload()` against the same instance refreshes the list and keeps the open thread. `reload()` after a different adapter instance resets selection and cached records, then loads the replacement store.
 
 ### Refetching the open thread
 
-`reload()` re-runs `list()`, which refreshes thread list metadata only. It does not touch the messages of the thread the user is looking at. When the open thread's server state changes out of band, so that nothing arrives over the stream (a human-in-the-loop interrupt raised by another process, a stalled stream, a status change picked up by polling), call `aui.threads.reloadMainThread()`:
+`reload()` against the same adapter instance re-runs `list()`, which refreshes thread list metadata only. It does not touch the messages of the thread the user is looking at. When the open thread's server state changes out of band, so that nothing arrives over the stream (a human-in-the-loop interrupt raised by another process, a stalled stream, a status change picked up by polling), call `aui.threads.reloadMainThread()`:
 
 ```tsx
 function RefetchOnInterrupt({ status }: { status: string }) {
@@ -230,13 +264,13 @@ A thread that has not been sent yet is left alone because it holds no remote sta
 
 What happens to a run in progress depends on the path. The remount path drops the runtime that was rendering the run; whether the run itself stops is up to that hook's unmount cleanup, which core cannot enforce. On the in-place path the runtime that declared the capability decides, since core does not stop the run for it. Either way this belongs on an event rather than a short timer: drive it from a state change like the one above, or skip the call while `useAuiState((s) => s.thread.isRunning)` is true.
 
-How the refetch happens depends on the runtime, in one of three ways. When it declares the capability, the thread runtime is reused: composer drafts survive, existing messages stay rendered while the fresh state loads, and the returned promise settles with the refetch, rejecting if it fails. A remote thread list without the capability remounts the runtime hook instead, which re-runs `load()` at the cost of discarding unsent composer input, and resolves once the new runtime attaches. The single and in-memory thread lists hold no remote state and have no hook to remount, so there it resolves without doing anything.
+How the refetch happens depends on the runtime, in one of three ways. When it declares the capability, the thread runtime is reused: composer drafts survive, existing messages stay rendered while the fresh state loads, and the returned promise settles with the refetch, rejecting if it fails. A remote thread list without the capability remounts the runtime hook instead, which re-runs `load()` at the cost of discarding unsent composer input, and resolves once the new runtime attaches. The single and in-memory thread lists have no hook to remount: they take the in-place path when their tap `ExternalThread` was given `onRefetchThread`, and resolve without doing anything when it was not.
 
 `useAuiState((s) => s.thread.capabilities.refetchThread)` reports which of those you would get, in place or not. It is not a signal for whether to offer a refresh at all: it is false on the remount path, where the call still does the work, and false again where the call does nothing.
 
-Both the LangGraph and Google ADK adapters register the in-place refetch capability when their runtime hook receives a `load` function; without one they fall back to the remount path. Other remote adapters take the remount path unless they provide the capability themselves.
+Both the LangGraph and Google ADK adapters register the in-place refetch capability when their runtime hook receives a `load` function; without one they fall back to the remount path. The Eve adapter registers it when the installed `eve` exposes `resume()` (0.44.1 and later), with no option to pass; on older releases it falls back like any other adapter, which for the single and in-memory thread lists it is usually paired with means the call resolves without doing anything. A refetch that lands during a run also settles differently across the three: LangGraph and Google ADK issue the load right away, so the promise settles at fetch latency and each decides on arrival how much of the snapshot a racing run leaves standing, while Eve queues the replay behind the in-flight turn, so its promise settles only once that turn parks. Other remote adapters take the remount path unless they provide the capability themselves.
 
-For an external store runtime, declare it with `onRefetchThread`, which is unrelated to `onReload` (that one re-generates an assistant message):
+For an external store runtime, declare it with `onRefetchThread`, which is unrelated to `onReload` (that one re-generates an assistant message); the tap `ExternalThread` accepts the same prop:
 
 ```ts
 useExternalStoreRuntime({
@@ -367,7 +401,13 @@ A few invariants worth knowing when wiring a custom UI on top of `loadMore()`:
       name: "unstable_Provider",
       type: "RemoteThreadListProviderComponent",
       description:
-        "Optional wrapper rendered around each active thread. Inject thread-scoped adapters (history, attachments) here.",
+        "Optional React wrapper rendered around each active thread by useRemoteThreadListRuntime when present. Inject thread-scoped adapters here. Omit it to let that host use unstable_useAdapters.",
+    },
+    {
+      name: "unstable_useAdapters",
+      type: "() => RuntimeAdapters | null | undefined",
+      description:
+        "Optional hook called by the RemoteThreadList store entry, and by useRemoteThreadListRuntime when unstable_Provider is omitted. Per-thread history requires the thread factory to be keyed with withKey.",
     },
   ]}
 />

package/.docs/raw/docs/runtimes/custom/assistant-transport.mdx

@@ -308,7 +308,7 @@ aui-state:[{"type":"set","path":["status"],"value":"completed"}]
   prepareSendCommandsRequest?: (body: SendCommandsRequestBody) => Record<string, unknown> | Promise<Record<string, unknown>>,
   capabilities?: { edit?: boolean },
   adapters?: { attachments?: AttachmentAdapter; history?: ThreadHistoryAdapter },
-  onResponse?: (response: Response) => void,
+  onResponse?: (response: Response) => void | Promise<void>,
   onFinish?: () => void,
   onError?: (error: Error, params: { commands: AssistantTransportCommand[]; updateState: (updater: (state: T) => T) => void }) => void | Promise<void>,
   onCancel?: (params: { commands: AssistantTransportCommand[]; updateState: (updater: (state: T) => T) => void; error?: Error }) => void

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -421,13 +421,13 @@ useEffect(() => {
 }, [isRunning, queue]);
 ```
 
-Queue policy on cancel, edit, and reload is host-owned. Call `queue.notifyCancelled()` in your `onCancel` handler before aborting so the cancelled run's settle pauses draining instead of dispatching the next item (the next send or run start resumes it), or call `queue.clear()` to drop the pending items. Call `queue.clear()` in your `onEdit` and `onReload` handlers so stale items do not drain onto the new branch.
+With a `createMessageQueue` adapter, cancelling pauses the queue for you: the runtime tells the queue before your `onCancel` runs, so the cancelled run's settle keeps the pending items instead of dispatching the next one, and the next send resumes draining. Call `queue.clear()` in `onCancel` instead if you want a cancel to drop them. A hand-rolled adapter has no such channel, so it owns its cancel policy the same way it owns the rest. Edit and reload stay host-owned: call `queue.clear()` in your `onEdit` and `onReload` handlers so stale items do not drain onto the new branch.
 
 ```tsx
 const runtime = useExternalStoreRuntime({
   // ...
   onCancel: async () => {
-    queue.notifyCancelled(); // or queue.clear() to drop pending items
+    // the runtime already paused the queue; clear() here to drop the items
     await cancelRun();
   },
   onEdit: async (message) => {
@@ -447,6 +447,10 @@ const runtime = useExternalStoreRuntime({
 
 ## Integration examples
 
+<Callout type="info">
+**Real-world example:** the [Claude Managed Agents guide](/docs/runtimes/claude-managed-agents) maps Anthropic-hosted agent sessions onto this runtime, with Anthropic's official [quickstart](https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/assistant-ui) as the runnable reference.
+</Callout>
+
 ### Redux
 
 ```tsx title="app/chatSlice.ts"

package/.docs/raw/docs/runtimes/langchain.mdx

@@ -262,7 +262,7 @@ Follow the [Ink setup](/docs/ink).
 
 ### Forwarding per-run config
 
-When a message is sent, its `runConfig.custom` (for example a selected mode or model) is forwarded on the underlying `useStream().submit` call as `config.configurable`. Read it in the graph from `config["configurable"]`; on LangGraph v1 the same values are also reachable through the Runtime `context`, which `config.configurable` is aliased to. This lets per-run app config reach the graph without extra wiring.
+When a message is sent, its `runConfig.custom` (for example a selected mode or model) is forwarded on the underlying `useStream().submit` call as `config.configurable`. Automatic tool-result resumes and the interrupt helpers (`useLangChainRespond`, `useLangChainRespondAll`, and `useLangChainSubmit(null, { command })`) reuse that same recorded `configurable` unless the caller passes `config`. Raw `useLangChainSubmit` / `useLangChainSend` calls that start a new run do not inherit it. The recording is session-scoped and does not survive a reload. Read it in the graph from `config["configurable"]`; on LangGraph v1 the same values are also reachable through the Runtime `context`, which `config.configurable` is aliased to. This lets per-run app config reach the graph without extra wiring.
 
 ## Reading custom state keys
 
@@ -744,8 +744,8 @@ Register the components with `makeAssistantDataUI`, keyed by the `UIMessage`'s `
 import {
   AssistantRuntimeProvider,
   makeAssistantDataUI,
-  Thread,
 } from "@assistant-ui/react";
+import { Thread } from "@/components/assistant-ui/thread";
 import { useStreamRuntime } from "@assistant-ui/react-langchain";
 
 const ChartUI = makeAssistantDataUI({

package/.docs/raw/docs/runtimes/langgraph/streaming.mdx

@@ -119,6 +119,10 @@ const runtime = useLangGraphRuntime({
 
 Render the pending messages with [`ComposerPrimitive.Queue`](/docs/api-reference/primitives/composer) and [`QueueItemPrimitive`](/docs/api-reference/primitives/queue-item).
 
+## Per-run config
+
+When a message is sent, its `runConfig` is forwarded to `stream` and, if you use `unstable_createLangGraphStream`, posted as the LangGraph SDK run `config`. Automatic frontend tool-result resumes and `useLangGraphSendCommand` reuse the `runConfig` of the run that produced the pending tool call or interrupt. An explicit `runConfig` on `useLangGraphSend` still wins. A thread refetch that still carries the interrupt keeps that owner. History loaded without local ownership stays unconfigured on resume; the recording is session-scoped and does not survive a reload.
+
 ## Next
 
 <Cards>

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

@@ -41,7 +41,7 @@ export function MyRuntimeProvider({
 ### Render the Thread
 
 ```tsx title="app/page.tsx"
-import { Thread } from "@assistant-ui/react";
+import { Thread } from "@/components/assistant-ui/thread";
 import { MyRuntimeProvider } from "./MyRuntimeProvider";
 
 export default function Page() {