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

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

@@ -227,7 +227,7 @@ export async function POST(
 
 ### Implement `RemoteThreadListAdapter`
 
-The adapter calls your endpoints. `unstable_Provider` injects the per-thread history adapter so messages persist alongside metadata.
+The adapter calls your endpoints. `unstable_useAdapters` injects the per-thread history adapter on the `RemoteThreadList` store entry and on `useRemoteThreadListRuntime` when `unstable_Provider` is omitted. `unstable_Provider` is an optional React face for that runtime. On the `RemoteThreadList` store entry, key the thread factory with `withKey(id, …)` so history reloads when the visible thread changes.
 
 <PlatformTabs>
 <Tab value="React">
@@ -244,6 +244,51 @@ import {
 import { createAssistantStream } from "assistant-stream";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        return { messages: [] };
+      },
+      async append() {},
+      withFormat: (fmt) => ({
+        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((row: any) =>
+              fmt.decode({
+                id: row.id,
+                parent_id: row.parent_id,
+                format: row.format,
+                content: row.content,
+              }),
+            ),
+          };
+        },
+        async append(item) {
+          const { remoteId } = await aui.threadListItem.initialize();
+          await fetch(`/api/threads/${remoteId}/messages`, {
+            method: "POST",
+            body: JSON.stringify({
+              id: fmt.getId(item.message),
+              parent_id: item.parentId,
+              format: fmt.format,
+              content: fmt.encode(item),
+            }),
+          });
+        },
+      }),
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 export const threadListAdapter: RemoteThreadListAdapter = {
   async list() {
     const rows = await fetch("/api/threads").then((r) => r.json());
@@ -295,50 +340,11 @@ export const threadListAdapter: RemoteThreadListAdapter = {
       controller.appendText(title);
     });
   },
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          return { messages: [] };
-        },
-        async append() {},
-        withFormat: (fmt) => ({
-          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((row: any) =>
-                fmt.decode({
-                  id: row.id,
-                  parent_id: row.parent_id,
-                  format: row.format,
-                  content: row.content,
-                }),
-              ),
-            };
-          },
-          async append(item) {
-            const { remoteId } = await aui.threadListItem.initialize();
-            await fetch(`/api/threads/${remoteId}/messages`, {
-              method: "POST",
-              body: JSON.stringify({
-                id: fmt.getId(item.message),
-                parent_id: item.parentId,
-                format: fmt.format,
-                content: fmt.encode(item),
-              }),
-            });
-          },
-        }),
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -359,6 +365,51 @@ import {
 import { createAssistantStream } from "assistant-stream";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        return { messages: [] };
+      },
+      async append() {},
+      withFormat: (fmt) => ({
+        async load() {
+          const { remoteId } = aui.threadListItem.getState();
+          if (!remoteId) return { messages: [] };
+          const rows = await fetch(
+            `${API_URL}/threads/${remoteId}/messages`,
+          ).then((r) => r.json());
+          return {
+            messages: rows.map((row: any) =>
+              fmt.decode({
+                id: row.id,
+                parent_id: row.parent_id,
+                format: row.format,
+                content: row.content,
+              }),
+            ),
+          };
+        },
+        async append(item) {
+          const { remoteId } = await aui.threadListItem.initialize();
+          await fetch(`${API_URL}/threads/${remoteId}/messages`, {
+            method: "POST",
+            body: JSON.stringify({
+              id: fmt.getId(item.message),
+              parent_id: item.parentId,
+              format: fmt.format,
+              content: fmt.encode(item),
+            }),
+          });
+        },
+      }),
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 export const threadListAdapter: RemoteThreadListAdapter = {
   async list() {
     const rows = await fetch(`${API_URL}/threads`).then((r) => r.json());
@@ -412,50 +463,11 @@ export const threadListAdapter: RemoteThreadListAdapter = {
       controller.appendText(title);
     });
   },
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          return { messages: [] };
-        },
-        async append() {},
-        withFormat: (fmt) => ({
-          async load() {
-            const { remoteId } = aui.threadListItem.getState();
-            if (!remoteId) return { messages: [] };
-            const rows = await fetch(
-              `${API_URL}/threads/${remoteId}/messages`,
-            ).then((r) => r.json());
-            return {
-              messages: rows.map((row: any) =>
-                fmt.decode({
-                  id: row.id,
-                  parent_id: row.parent_id,
-                  format: row.format,
-                  content: row.content,
-                }),
-              ),
-            };
-          },
-          async append(item) {
-            const { remoteId } = await aui.threadListItem.initialize();
-            await fetch(`${API_URL}/threads/${remoteId}/messages`, {
-              method: "POST",
-              body: JSON.stringify({
-                id: fmt.getId(item.message),
-                parent_id: item.parentId,
-                format: fmt.format,
-                content: fmt.encode(item),
-              }),
-            });
-          },
-        }),
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -478,6 +490,51 @@ import {
 import { createAssistantStream } from "assistant-stream";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        return { messages: [] };
+      },
+      async append() {},
+      withFormat: (fmt) => ({
+        async load() {
+          const { remoteId } = aui.threadListItem.getState();
+          if (!remoteId) return { messages: [] };
+          const rows = await fetch(
+            `${API_URL}/threads/${remoteId}/messages`,
+          ).then((r) => r.json());
+          return {
+            messages: rows.map((row: any) =>
+              fmt.decode({
+                id: row.id,
+                parent_id: row.parent_id,
+                format: row.format,
+                content: row.content,
+              }),
+            ),
+          };
+        },
+        async append(item) {
+          const { remoteId } = await aui.threadListItem.initialize();
+          await fetch(`${API_URL}/threads/${remoteId}/messages`, {
+            method: "POST",
+            body: JSON.stringify({
+              id: fmt.getId(item.message),
+              parent_id: item.parentId,
+              format: fmt.format,
+              content: fmt.encode(item),
+            }),
+          });
+        },
+      }),
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 export const threadListAdapter: RemoteThreadListAdapter = {
   async list() {
     const rows = await fetch(`${API_URL}/threads`).then((r) => r.json());
@@ -531,50 +588,11 @@ export const threadListAdapter: RemoteThreadListAdapter = {
       controller.appendText(title);
     });
   },
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          return { messages: [] };
-        },
-        async append() {},
-        withFormat: (fmt) => ({
-          async load() {
-            const { remoteId } = aui.threadListItem.getState();
-            if (!remoteId) return { messages: [] };
-            const rows = await fetch(
-              `${API_URL}/threads/${remoteId}/messages`,
-            ).then((r) => r.json());
-            return {
-              messages: rows.map((row: any) =>
-                fmt.decode({
-                  id: row.id,
-                  parent_id: row.parent_id,
-                  format: row.format,
-                  content: row.content,
-                }),
-              ),
-            };
-          },
-          async append(item) {
-            const { remoteId } = await aui.threadListItem.initialize();
-            await fetch(`${API_URL}/threads/${remoteId}/messages`, {
-              method: "POST",
-              body: JSON.stringify({
-                id: fmt.getId(item.message),
-                parent_id: item.parentId,
-                format: fmt.format,
-                content: fmt.encode(item),
-              }),
-            });
-          },
-        }),
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -728,7 +746,7 @@ Send a message in a fresh thread. Check the database:
 
 ## Notes
 
-- **First-message race.** `append` may fire before the thread row exists. The `unstable_Provider` example above always awaits `aui.threadListItem.initialize()` before writing; do the same in any custom implementation.
+- **First-message race.** `append` may fire before the thread row exists. The example above always awaits `aui.threadListItem.initialize()` before writing; do the same in any custom implementation.
 - **Reload after async auth.** If `auth()` resolves after the initial `list()` call, threads won't appear until the user refreshes. Call `aui.threads.reload()` from a `useEffect` watching the session. Pattern is documented in [threads](/docs/runtimes/concepts/threads#reloading-after-async-authentication).
 - **Format string.** The `format` column is *not* a free-text label; it identifies the on-disk shape so multiple runtimes can coexist. Don't strip it. Don't make assumptions about its value (`useChatRuntime` is responsible for setting and decoding it).
 - **Pending approvals need `update`.** Tool call approvals persist across reloads only when the formatted adapter implements `update`; omitting it keeps the pre-approval snapshot out of storage by design.

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/suggestion.mdx

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

@@ -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/runtimes/ag-ui/runtime-options.mdx

@@ -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.
 
@@ -183,8 +195,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 +224,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/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/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`. |