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

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

@@ -133,16 +133,96 @@ const aui = useAui(scopes, { parent });
 
 // After
 const Scoped = ({ children }) => {
-  const aui = useAui(scopes); // extends the AuiProvider parent
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+  const aui = useAui();
+  const config = AuiConfig(scopes);
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 };
 
-<AuiProvider value={parent}>
+const rootConfig = AuiConfig({});
+
+<AuiProvider extends={parent} config={rootConfig}>
   <Scoped />
 </AuiProvider>;
 ```
 
-Where `{ parent: null }` was used to detach from context, `<AuiProvider value={null}>` now provides an isolated empty root (experimental).
+Where `{ parent: null }` was used to detach from context, `<AuiProvider extends={null} config={config}>` where `const config = AuiConfig({})` now provides an isolated empty root.
+
+## `AuiProvider` Grammar
+
+`AuiProvider` takes a `config` built with `AuiConfig(...)` — raw object literals are a type error. At the top level, `config` alone creates the subtree's client. Nested under a parent provider, `extends` is mandatory: `extends={aui}` extends the parent, `extends={null}` isolates (dev-enforced). `ref` receives the resulting client after mount.
+
+```tsx
+const aui = useAui();
+const config = AuiConfig({ tools: Tools({ toolkit }) });
+
+// Top-level root
+<AuiProvider config={config}>
+
+// Nested: extend the parent
+<AuiProvider extends={aui} config={config}>
+
+// Nested: isolate from the parent
+<AuiProvider extends={null} config={config}>
+```
+
+`AuiConfig` is exported from `@assistant-ui/store` and re-exported from `@assistant-ui/react`, `@assistant-ui/react-native`, and `@assistant-ui/react-ink`.
+
+### `value` Prop Deprecated
+
+```tsx
+// Before
+<AuiProvider value={client}>
+<AuiProvider value={null}>
+
+// After
+const config = AuiConfig({});
+
+<AuiProvider extends={client} config={config}>
+<AuiProvider extends={null} config={config}>
+```
+
+The replacement exposes a client extending the given one, not the same instance — `useAui()` beneath it returns the new client, with scope access delegating to `client`. The deprecated `value={client}` form behaves the same way: it also exposes a derived client rather than the exact instance, and the given client must implement `subscribe`.
+
+### `useAui({ ... })` Extension Overload Deprecated
+
+```tsx
+// Before
+const aui = useAui({ tools: Tools({ toolkit }) });
+return <AuiProvider value={aui}>{children}</AuiProvider>;
+
+// After
+const aui = useAui();
+const config = AuiConfig({ tools: Tools({ toolkit }) });
+return (
+  <AuiProvider extends={aui} config={config}>
+    {children}
+  </AuiProvider>
+);
+```
+
+Where the extended client was passed to `<AssistantRuntimeProvider aui={aui}>`, use the new `config` prop instead — the scopes are provided alongside the runtime's threads scope:
+
+```tsx
+// Before
+const aui = useAui({ tools: Tools({ toolkit }) });
+return (
+  <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    {children}
+  </AssistantRuntimeProvider>
+);
+
+// After
+const config = AuiConfig({ tools: Tools({ toolkit }) });
+return (
+  <AssistantRuntimeProvider runtime={runtime} config={config}>
+    {children}
+  </AssistantRuntimeProvider>
+);
+```
 
 ## Still Deprecated (not removed)
 

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

@@ -53,7 +53,7 @@ import { AttachmentPrimitive, ComposerPrimitive } from "@assistant-ui/react";
 </ComposerPrimitive.Root>
 ```
 
-`Root` renders a `<div>`, `unstable_Thumb` renders a `<div>` showing the file extension with a leading dot (e.g., `.pdf`), `Name` renders plain text, and `Remove` renders a `<button>`.
+`Root` renders a `<div>`, `unstable_Thumb` renders a `<div>` showing the file extension with a leading dot (e.g., `.pdf`), or the attachment type (e.g., `image`) when the filename has no extension (including leading-dot names like `.env`), `Name` renders plain text, and `Remove` renders a `<button>`. If you pass `children` to `unstable_Thumb`, they override that text.
 
 <Callout type="info">
 Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRuntimeProvider` with a runtime (for example `useLocalRuntime(...)`). See [Pick a Runtime](/docs/runtimes/pick-a-runtime).
@@ -124,7 +124,7 @@ Container for a single attachment item. Renders a `<div>` element unless `asChil
 
 ### unstable_Thumb
 
-Thumbnail slot for attachment previews. Renders a `<div>` element unless `asChild` is set.
+Thumbnail slot for attachment previews. Renders a `<div>` element unless `asChild` is set. By default it shows the file extension with a leading dot (e.g., `.pdf`); if you pass `children`, they override the automatic text.
 
 ```tsx
 <AttachmentPrimitive.unstable_Thumb className="flex size-10 items-center justify-center rounded bg-muted text-xs" />

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

@@ -258,7 +258,7 @@ Renders a single attachment at a specific index.
 
 ### AttachmentDropzone
 
-Drag-and-drop zone for file attachments. Sets `data-dragging` when a file is being dragged over it. Renders a `<div>` element unless `asChild` is set.
+Drag-and-drop zone for file attachments. Sets `data-dragging` when a file is being dragged over it and the runtime supports attachments; without the attachments capability the dropzone accepts no files and shows no highlight. Non-file drags (text, links) are ignored. Renders a `<div>` element unless `asChild` is set.
 
 ```tsx
 <ComposerPrimitive.AttachmentDropzone className="rounded-xl border-2 border-dashed data-[dragging]:border-primary data-[dragging]:bg-primary/5">
@@ -507,7 +507,7 @@ Wrap your composer with `AttachmentDropzone` to support dragging files directly
 </ComposerPrimitive.AttachmentDropzone>
 ```
 
-The dropzone sets `data-dragging` when a file is being dragged over it, so you can style the active state with CSS.
+The dropzone sets `data-dragging` when a file is being dragged over it, so you can style the active state with CSS. It requires the runtime's attachments capability (an attachment adapter); without it the dropzone stays inert.
 
 ### With Voice Input
 

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

@@ -112,6 +112,37 @@ Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRun
 For most new code, prefer `MessagePrimitive.Parts` with a `children` render function. When you need adjacent grouping, use `MessagePrimitive.GroupedParts`.
 </Callout>
 
+### Part Types
+
+A message part is one of three kinds, and which kind a new capability belongs to is decided by the list below rather than case by case.
+
+| Kind | Parts | Grows by |
+|------|-------|----------|
+| Modality | `text`, `image`, `file` | Never. `file` carries every non-image binary modality through its `mimeType`. |
+| Provider channel | `reasoning`, `source`, `tool-call`, `generative-ui` | Never. These mirror channels a model already emits. |
+| Extensibility | `data` | Freely, through `name`. This is the growth path for anything app-level. |
+
+`file` is the media carrier. Audio, video, PDFs and everything else are `{ type: "file", mimeType: "audio/mpeg" }` rather than part types of their own, so one renderer and one converter branch handle them all. The payload can be inline base64 or a URL; `sourceType` additionally allows an opaque storage id, which the LangChain-family runtimes honor and other adapters ignore.
+
+Anything that is not a modality the model consumes or a channel it emits is a `data` part, routed by `name`:
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    data: {
+      by_name: { citation: MyCitation },
+      Fallback: MyDataFallback,
+    },
+  }}
+/>
+```
+
+<Callout type="warn">
+`Unstable_AudioMessagePart` and the `Unstable_Audio` slot are deprecated. The audio part cannot carry a filename, has no way to declare how its payload goes on the wire (no `sourceType`, so no storage id), and exists only on user messages, so a model that returns audio has no way to express it. Send audio as a `file` part with an `audio/*` mime type instead, and give it a filename.
+
+Adapter coverage for the file path is still uneven, so check your adapter's converter before relying on file parts. Known so far: `react-pi` and the assistant-transport runtime have no file part on their user-content surface at all, so one is dropped; `react-data-stream` carries the payload but not the filename. Existing audio parts keep working; they will not gain fields.
+</Callout>
+
 ### Tool Resolution
 
 Tool call parts resolve in this order:
@@ -149,7 +180,8 @@ Returning `null` still allows registered tool UIs and data renderer UIs to rende
 - `components.ChainOfThought` takes over all reasoning and tool-call rendering (mutually exclusive with `ToolGroup`, `ReasoningGroup`, `tools`, and `Reasoning`). This legacy path is deprecated; use `MessagePrimitive.GroupedParts` for grouped Chain of Thought in new code.
 - `data.by_name` and `data.Fallback` let you route custom data part types
 - `Quote` renders quoted message references from metadata
-- `Empty` and `Unstable_Audio` are available for edge and experimental rendering paths
+- `Empty` is available for edge rendering paths
+- `Unstable_Audio` is deprecated; render `audio/*` from the `File` slot instead
 
 ```tsx
 <MessagePrimitive.Parts

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

@@ -106,7 +106,7 @@ Both render a `<span>` and accept `children` to override the value from state:
 
 `Trigger`'s `send` prop controls what happens on click:
 
-- **`send={true}`**: immediately sends the suggestion as a new message. When the thread is running, it falls back to populating the composer instead.
+- **`send={true}`**: immediately sends the suggestion as a new message. While a run is in progress, the suggestion is queued on runtimes that support queueing (leaving the composer draft untouched); otherwise the trigger is disabled.
 - **`send={false}`** (default): populates the composer text so the user can edit before sending
 
 ```tsx

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

@@ -155,12 +155,22 @@ export default defineToolkit({
 ```
 
 ```tsx title="ToolProvider.tsx"
-import { AuiProvider, Tools, useAui } from "@assistant-ui/react-native";
+import {
+  AuiConfig,
+  AuiProvider,
+  Tools,
+  useAui,
+} from "@assistant-ui/react-native";
 import toolkit from "./weather-toolkit";
 
 function ToolProvider({ children }: { children: React.ReactNode }) {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 
@@ -218,7 +228,7 @@ export function useMyToolToolkit(someOuterProp: string) {
 }
 ```
 
-Import the toolkit hook, pass its result to `useAui({ tools: Tools({ toolkit }) })`, and provide the returned `aui` with `AuiProvider`, as shown in the [Tools](#tools) section above.
+Import the toolkit hook, hoist `const aui = useAui()` and `const config = AuiConfig({ tools: Tools({ toolkit }) })` in the component body, and mount it with `<AuiProvider extends={aui} config={config}>`, as shown in the [Tools](#tools) section above.
 
 ### makeAssistantDataUI
 

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

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

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

@@ -437,7 +437,7 @@ Renders message content parts via a `components` prop. Tool call and data parts
 | `Reasoning` | `ReasoningMessagePartComponent` | Reasoning part renderer |
 | `Source` | `SourceMessagePartComponent` | Source part renderer |
 | `File` | `FileMessagePartComponent` | File part renderer |
-| `Unstable_Audio` | `AudioMessagePartComponent` | Audio part renderer (experimental) |
+| `Unstable_Audio` | `Unstable_AudioMessagePartComponent` | Audio part renderer (deprecated, render `audio/*` from `File`) |
 | `tools` | `{ by_name?, Fallback? }` or `{ Override }` | Tool call rendering config — use `by_name` to map tool names to components, `Fallback` for unregistered tools, or `Override` to handle all tool calls |
 | `data` | `{ by_name?, Fallback? }` | Data part rendering config — use `by_name` to map data event names, `Fallback` for unmatched events |
 | `Empty` | `EmptyMessagePartComponent` | Component shown for empty messages |
@@ -541,7 +541,7 @@ Container `View` for an attachment.
 
 ### AttachmentPrimitive.Thumb
 
-`Text` component displaying the file extension (e.g. `.pdf`).
+`Text` component displaying the file extension (e.g. `.pdf`), or the attachment type (e.g. `image`) when the filename has no extension (including leading-dot names like `.env`). If you pass `children`, they override that text.
 
 ```tsx
 <AttachmentPrimitive.Thumb style={styles.extension} />

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

@@ -35,7 +35,7 @@ import { openai } from "@ai-sdk/openai";
 
 export async function POST(req: Request) {
   const { messages } = await req.json();
-  const result = streamText({ model: openai("gpt-5.4-nano"), messages });
+  const result = streamText({ model: openai("gpt-5.6-luna"), messages });
   return result.toDataStreamResponse();
 }
 ```

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

@@ -40,7 +40,7 @@ export const maxDuration = 30;
 export async function POST(req: Request) {
   const { messages }: { messages: Message[] } = await req.json();
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages,
     tools: {
       get_current_weather: tool({

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

@@ -92,7 +92,7 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages), // async in v6
     tools: {
       get_current_weather: tool({
@@ -245,7 +245,7 @@ export async function POST(req: Request) {
   } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     system,
     messages: await convertToModelMessages(messages),
     tools: {
@@ -258,7 +258,7 @@ export async function POST(req: Request) {
 }
 ```
 
-Frontend tools are registered through `useAui` (see the [tools guide](/docs/tools/defining-tools)) and serialized for the backend via `frontendTools`.
+Frontend tools are registered through the provider's `config` (see the [tools guide](/docs/tools/defining-tools)) and serialized for the backend via `frontendTools`.
 
 ## Multi-step tool calls
 
@@ -276,7 +276,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: {
       /* ... */
@@ -305,7 +305,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: {
       deploy: tool({
@@ -356,9 +356,9 @@ Render the gate with a toolkit entry. The `approval` field carries the gate stat
 import { useChat } from "@ai-sdk/react";
 import {
   AssistantRuntimeProvider,
+  AuiConfig,
   defineToolkit,
   Tools,
-  useAui,
 } from "@assistant-ui/react";
 import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
 import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
@@ -397,10 +397,9 @@ export default function Page() {
     sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
   });
   const runtime = useAISDKRuntime(chat);
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       <Thread />
     </AssistantRuntimeProvider>
   );
@@ -424,7 +423,7 @@ import { openai } from "@ai-sdk/openai";
 export async function POST(req: Request) {
   const { messages } = await req.json();
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(injectQuoteContext(messages)),
   });
   return result.toUIMessageStreamResponse();

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

@@ -90,7 +90,7 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages), // async in v7
     tools: {
       get_current_weather: tool({
@@ -245,7 +245,7 @@ export async function POST(req: Request) {
   } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     system,
     messages: await convertToModelMessages(messages),
     tools: {
@@ -260,7 +260,7 @@ export async function POST(req: Request) {
 }
 ```
 
-Frontend tools are registered through `useAui` (see the [tools guide](/docs/tools/defining-tools)) and serialized for the backend via `frontendTools`.
+Frontend tools are registered through the provider's `config` (see the [tools guide](/docs/tools/defining-tools)) and serialized for the backend via `frontendTools`.
 
 ## Multi-step tool calls
 
@@ -280,7 +280,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: {
       /* ... */
@@ -311,7 +311,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: {
       deploy: tool({
@@ -368,9 +368,9 @@ Render the gate with a toolkit entry. The `approval` field carries the gate stat
 import { useChat } from "@ai-sdk/react";
 import {
   AssistantRuntimeProvider,
+  AuiConfig,
   defineToolkit,
   Tools,
-  useAui,
 } from "@assistant-ui/react";
 import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
 import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
@@ -410,10 +410,9 @@ export default function Page() {
     sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
   });
   const runtime = useAISDKRuntime(chat);
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       <Thread />
     </AssistantRuntimeProvider>
   );
@@ -439,7 +438,7 @@ import { openai } from "@ai-sdk/openai";
 export async function POST(req: Request) {
   const { messages } = await req.json();
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(injectQuoteContext(messages)),
   });
   return createUIMessageStreamResponse({

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

@@ -209,6 +209,45 @@ function ReloadOnAuth() {
 
 `reload()` discards in-flight responses from superseded calls, so it is safe to invoke on every auth transition.
 
+### 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()`:
+
+```tsx
+function RefetchOnInterrupt({ status }: { status: string }) {
+  const aui = useAui();
+  useEffect(() => {
+    if (status !== "interrupted") return;
+    aui.threads.reloadMainThread().catch(reportError);
+  }, [status]);
+  return null;
+}
+```
+
+What the promise means depends on the path. On the remount path, it resolves as soon as the replacement runtime attaches, which happens before that runtime's `load()` has started, so awaiting it does not mean the thread is fresh and a failed load cannot reach the caller. On the in-place path, it settles with the refetch itself and rejects when it fails, which is why the example above still handles the rejection.
+
+A thread that has not been sent yet is left alone because it holds no remote state.
+
+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.
+
+`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.
+
+For an external store runtime, declare it with `onRefetchThread`, which is unrelated to `onReload` (that one re-generates an assistant message):
+
+```ts
+useExternalStoreRuntime({
+  messages,
+  onNew,
+  onRefetchThread: async () => {
+    setMessages(await fetchMessages(threadId));
+  },
+});
+```
+
 ### Paginating the thread list
 
 If your backend returns thread pages, return a `nextCursor` from `list()` and consume `aui.threads.hasMore` plus `aui.threads.loadMore()` in the UI. The runtime threads `params.after` back through `list()` on every `loadMore()`; the initial call passes no `params`, so treat a missing `after` as "first page". `reload()` resets the cursor so the next load starts from page 1 again.
@@ -326,7 +365,7 @@ A few invariants worth knowing when wiring a custom UI on top of `loadMore()`:
     },
     {
       name: "unstable_Provider",
-      type: "ComponentType<PropsWithChildren>",
+      type: "RemoteThreadListProviderComponent",
       description:
         "Optional wrapper rendered around each active thread. Inject thread-scoped adapters (history, attachments) here.",
     },

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

@@ -300,6 +300,7 @@ aui-state:[{"type":"set","path":["status"],"value":"completed"}]
   initialState: T,
   api: string,
   resumeApi?: string,
+  resumeStateApi?: string,
   protocol?: "data-stream" | "assistant-transport",
   converter: (state: T, connectionMetadata: ConnectionMetadata) => AssistantTransportState,
   headers?: Record<string, string> | Headers | (() => Promise<Record<string, string> | Headers>),
@@ -519,6 +520,23 @@ const runtime = useAssistantTransportRuntime({
 });
 ```
 
+Setting `resumeStateApi` additionally hydrates resumed runs from the server-retained starting state. It requires a sync server that serves the initial-state route; do not configure it against a server without one, since a failing preflight fails the resume closed:
+
+```tsx
+const runtime = useAssistantTransportRuntime({
+  // ...
+  resumeStateApi: "http://localhost:8010/initial-state",
+});
+```
+
+Before resuming, the runtime posts `{ threadId }` to `resumeStateApi`. The endpoint must return the state that started the active run together with its identity:
+
+```json
+{ "runId": "8b3a...", "state": { "messages": [] } }
+```
+
+The runtime replaces its local base with this snapshot and includes `runId` in the resume request; the request carries no `state`, since the server replays from the snapshot it retained. A sync server should reject the resume when that ID no longer identifies the same run, preventing replay operations from being applied to a drifted or replaced base state. When no run is active, the endpoint responds `204 No Content` and the runtime skips the resume without raising an error. On a resume, `runId` takes precedence over fields supplied through `body` and survives `prepareSendCommandsRequest`; any `state` either of them supplies is stripped.
+
 ```tsx
 import { useAui } from "@assistant-ui/react";
 import { useEffect, useRef } from "react";

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

@@ -207,6 +207,7 @@ Each handler enables a specific UI feature.
 | `onEdit` | Message edit button |
 | `onReload` | Regenerate button |
 | `onCancel` | Cancel button while generating |
+| `onRefetchThread` | `threads.reloadMainThread()` refetching the open thread in place |
 | `onAddToolResult` | Client-side tool result handoff |
 | `queue` | Queueing messages sent while a run is in progress |
 
@@ -395,7 +396,9 @@ const runtime = useExternalStoreRuntime({
 
 By default, sending while the thread is running is disabled. Provide a `queue` adapter to buffer a message sent during a run and process it once the run settles. The pending message is exposed on `composer.queue` and renders through [`ComposerPrimitive.Queue`](/docs/api-reference/primitives/composer).
 
-The `createMessageQueue` helper owns the FIFO ordering and the in-flight guard. Supply a driver that runs a message, pass its `adapter` to the runtime, and tell the queue when a run starts (`notifyBusy()`, so concurrent sends buffer) and ends (`notifyIdle()`).
+The `createMessageQueue` helper owns the two-lane ordering and the in-flight guard: `steerItems` drain before `items`, and within each lane items drain in order. Supply a driver that runs a message, pass its `adapter` to the runtime, and tell the queue when a run starts (`notifyBusy()`, so concurrent sends buffer) and ends (`notifyIdle()`).
+
+A hand-rolled adapter must implement the same contract: `items` and `steerItems` expose the lanes (each item carries a required `parts` projection of its content), `enqueue`/`steer` add to a lane, and `move(queueItemId, placement)` repositions with fail-fast anchors — unknown ids or anchors throw rather than being coerced. Individual items are addressable through `composer.queueItem({ id })` (or by index).
 
 ```tsx
 import { useEffect, useRef, useState } from "react";
@@ -418,6 +421,26 @@ 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.
+
+```tsx
+const runtime = useExternalStoreRuntime({
+  // ...
+  onCancel: async () => {
+    queue.notifyCancelled(); // or queue.clear() to drop pending items
+    await cancelRun();
+  },
+  onEdit: async (message) => {
+    queue.clear();
+    // ...
+  },
+  onReload: async (parentId) => {
+    queue.clear();
+    // ...
+  },
+});
+```
+
 ## Multi-thread
 
 `ExternalStoreRuntime` uses `ExternalStoreThreadListAdapter` (synchronous, inline). See [threads](/docs/runtimes/concepts/threads#externalstorethreadlistadapter) for the contract and best practices on keeping `currentThreadId` in sync with your store.
@@ -787,6 +810,12 @@ useExternalStoreRuntime({
       type: "() => Promise<void>",
       description: "Handler for cancelling the current generation.",
     },
+    {
+      name: "onRefetchThread",
+      type: "() => Promise<void>",
+      description:
+        "Handler for re-fetching this thread's state in place, driving threads.reloadMainThread(). Unrelated to onReload, which re-generates an assistant message.",
+    },
     {
       name: "onAddToolResult",
       type: "(options: AddToolResultOptions) => Promise<void> | Void",