@assistant-ui/mcp-docs-server 0.1.31 → 0.1.33

package/.docs/raw/docs/runtimes/a2a/client-and-hooks.mdx

@@ -3,9 +3,9 @@ title: Client and hooks
 description: A2AClient, useA2ARuntime options, hooks, task states, artifacts, errors.
 ---
 
-import { Network } from "lucide-react";
+import { A2AIcon } from "@/components/icons/a2a";
 
-Deep dive on the runtime's API surface. Start with [overview](/docs/runtimes/a2a) and [quickstart](/docs/runtimes/a2a/quickstart) if you have not already.
+Deep dive on the runtime's API surface. Start with [overview](/docs/runtimes/a2a/overview) and [quickstart](/docs/runtimes/a2a/quickstart) if you have not already.
 
 ## A2AClient
 
@@ -19,6 +19,7 @@ const client = new A2AClient({
   headers: { Authorization: "Bearer <token>" },
   tenant: "my-org",
   extensions: ["urn:a2a:ext:my-extension"],
+  fetchOptions: { credentials: "include" },
 });
 ```
 
@@ -37,6 +38,7 @@ const runtime = useA2ARuntime({ client });
 | `headers` | `Record<string, string>` or `() => Record<string, string>` | Static or dynamic headers (e.g. for auth tokens). |
 | `tenant` | `string` | Tenant ID for multi-tenant servers (prepended to URL paths). |
 | `extensions` | `string[]` | Extension URIs to negotiate via `A2A-Extensions` header. |
+| `fetchOptions` | `RequestInit` (partial) | Extra fetch options applied to every request (e.g. `{ credentials: "include" }`). `headers`, `body`, `method`, and `signal` are managed internally. |
 
 ### Client methods
 
@@ -67,6 +69,7 @@ Pass either a pre-built `client` or a `baseUrl` (the runtime creates a client fo
 | `tenant` | `string` | Tenant ID for multi-tenant servers. Only used with `baseUrl`. |
 | `headers` | `Record<string, string>` or `() => Record<string, string>` | Headers for the auto-created client. |
 | `extensions` | `string[]` | Extension URIs to negotiate. Only used with `baseUrl`. |
+| `fetchOptions` | `RequestInit` (partial) | Extra fetch options for the auto-created client (e.g. `{ credentials: "include" }`). `headers`, `body`, `method`, and `signal` are managed internally. Only used with `baseUrl`. |
 | `contextId` | `string` | Initial context ID for the conversation. |
 | `configuration` | `A2ASendMessageConfiguration` | Default send message configuration. |
 | `onError` | `(error: Error) => void` | Error callback. |
@@ -378,10 +381,10 @@ This prepends `/{tenant}` to all API paths (e.g. `/my-org/message:send`).
 
 <Cards>
   <Card
-    icon={<Network width={20} height={20} />}
+    icon={<A2AIcon width={20} height={20} />}
     title="A2A overview"
     description="What A2A is and when to pick it."
-    href="/docs/runtimes/a2a"
+    href="/docs/runtimes/a2a/overview"
   />
   <Card
     title="Quickstart"

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

@@ -1,6 +1,6 @@
 ---
-title: Overview
-description: Connect to any A2A v1.0 protocol-compliant agent server.
+title: A2A Agent Runtime
+description: Connect any A2A v1.0 protocol-compliant agent server to a React chat UI with assistant-ui — full streaming, tool calls, and message metadata supported.
 ---
 
 `@assistant-ui/react-a2a` is a runtime adapter for the [A2A (Agent-to-Agent) v1.0 protocol](https://github.com/a2aproject/A2A). Use it when your backend speaks A2A; the adapter handles the wire protocol so you can focus on the UI.

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

@@ -1,6 +1,6 @@
 ---
-title: Overview
-description: Connect to AG-UI (Agent-User Interaction) protocol agents.
+title: AG-UI Agent Runtime
+description: Wire AG-UI (Agent-User Interaction) protocol agents into a React chat UI with assistant-ui — bidirectional events, generative UI, and human-in-the-loop.
 ---
 
 `@assistant-ui/react-ag-ui` is a runtime adapter for the [AG-UI (Agent-User Interaction) protocol](https://github.com/ag-ui-protocol/ag-ui). It lets your assistant-ui frontend speak to any AG-UI-compliant agent server, including CopilotKit-based backends.

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

@@ -62,13 +62,43 @@ const runtime = useAgUiRuntime({
 });
 ```
 
+## Interrupts (experimental)
+
+<Callout type="warn">
+The interrupt API is experimental and may change without notice.
+</Callout>
+
+When the agent emits `RUN_FINISHED` with `outcome = { type: "interrupt", interrupts: [...] }`, the active assistant message is marked `requires-action` with `reason: "interrupt"` and the `Interrupt[]` payload is written to `metadata.custom.agui.interrupts`. Render an approval / input UI from there.
+
+`useAgUiRuntime` returns an `AgUiAssistantRuntime` with two extra methods:
+
+| Method | Description |
+| --- | --- |
+| `unstable_getPendingInterrupts(): readonly AgUiInterrupt[]` | Snapshot of the open interrupts on the most recent assistant message. |
+| `unstable_submitInterruptResponses(responses: ResumeEntry[]): Promise<void>` | Submits one `ResumeEntry` per open interrupt and resumes the run. |
+
+`responses` must address every open interrupt; missing entries, unknown ids, or expired interrupts (`expiresAt`) reject before any network call. Each entry is `{ interruptId, status: "resolved" | "cancelled", payload? }`. The next `RunAgentInput` carries `resume: ResumeEntry[]`.
+
+```tsx
+const runtime = useAgUiRuntime({ agent });
+const pending = runtime.unstable_getPendingInterrupts();
+
+await runtime.unstable_submitInterruptResponses(
+  pending.map((i) => ({
+    interruptId: i.id,
+    status: "resolved",
+    payload: { approved: true },
+  })),
+);
+```
+
 ## Supported events
 
 The runtime parses the AG-UI event stream and maps each event type to assistant-ui state.
 
 | Event | Effect |
 | --- | --- |
-| `RUN_STARTED` / `RUN_FINISHED` | Toggles thread `isRunning`. |
+| `RUN_STARTED` / `RUN_FINISHED` | Toggles thread `isRunning`. `RUN_FINISHED.outcome` is honored (success / interrupt). |
 | `RUN_CANCELLED` | Marks the in-flight assistant message as cancelled. |
 | `RUN_ERROR` | Marks the message as errored; fires `onError`. |
 | `TEXT_MESSAGE_START` / `_CONTENT` / `_END` | Streams text content into an assistant message. |
@@ -98,6 +128,7 @@ The runtime parses the AG-UI event stream and maps each event type to assistant-
 | Message editing | Yes |
 | Message reload | Yes |
 | Run resumption | Yes |
+| Interrupts (human-in-the-loop) | Experimental (`unstable_*` API, see [Interrupts](#interrupts-experimental)) |
 | Multi-thread | Experimental (`adapters.threadList`) |
 | History persistence | Via [history adapter](/docs/runtimes/concepts/adapters#history-adapter) |
 

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

@@ -1,6 +1,6 @@
 ---
-title: Overview
-description: Vercel AI SDK integration for assistant-ui across major versions.
+title: Vercel AI SDK Runtime
+description: Connect the Vercel AI SDK to a React chat UI via assistant-ui — useChat hooks, custom transports, frontend tools, attachments, multi-step agents, and token usage.
 ---
 
 import { VercelIcon } from "@/components/icons/vercel";

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-4"), messages });
+  const result = streamText({ model: openai("gpt-5.4-nano"), messages });
   return result.toDataStreamResponse();
 }
 ```
@@ -53,7 +53,10 @@ import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
 import { Thread } from "@/components/assistant-ui/thread";
 
 export default function Home() {
-  const runtime = useDataStreamRuntime({ api: "/api/chat" });
+  const runtime = useDataStreamRuntime({
+    api: "/api/chat",
+    protocol: "data-stream",
+  });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <div className="h-full">
@@ -64,6 +67,8 @@ export default function Home() {
 }
 ```
 
+AI SDK v4's `toDataStreamResponse()` emits the data stream wire format, so `protocol: "data-stream"` is required to pair with it; the default `protocol: "ui-message-stream"` expects the SSE format introduced in AI SDK v6.
+
 </Step>
 </Steps>
 

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-4o"),
+    model: openai("gpt-5.4-nano"),
     messages,
     tools: {
       get_current_weather: tool({

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

@@ -254,7 +254,7 @@ export async function POST(req: Request) {
 }
 ```
 
-Frontend tools are registered through `useAui` (see the [tools guide](/docs/guides/tools)) and serialized for the backend via `frontendTools`.
+Frontend tools are registered through `useAui` (see the [tools guide](/docs/tools/defining-tools)) and serialized for the backend via `frontendTools`.
 
 ## Multi-step tool calls
 
@@ -286,6 +286,127 @@ export async function POST(req: Request) {
 
 Without a `stopWhen`, AI SDK runs a single inference step. Set `stepCountIs` (or one of AI SDK's other stop conditions) when your tools chain multiple calls.
 
+## Server-side tool approval
+
+AI SDK v6 lets a tool gate its own execution with `needsApproval`. The server pauses, emits an `approval-requested` part, and resumes once the client posts an approval response. assistant-ui surfaces the gate as `approval` on the tool part and adds a `respondToApproval` prop on the renderer, so tool components stay decoupled from `chatHelpers`.
+
+On the backend, mark the tool with `needsApproval` (boolean or function):
+
+```ts title="@/app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages, tool } from "ai";
+import { z } from "zod";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-5.4-mini"),
+    messages: await convertToModelMessages(messages),
+    tools: {
+      deploy: tool({
+        description: "Deploy the current build to an environment.",
+        inputSchema: z.object({ target: z.string() }),
+        needsApproval: ({ input }) => input.target === "production",
+        execute: async ({ target }) => ({ deployed: target }),
+      }),
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+On the client, configure `useChat` with `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses` so the response is sent back to the server when the user decides:
+
+```tsx title="@/app/page.tsx"
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import {
+  AssistantRuntimeProvider,
+  useAISDKRuntime,
+} from "@assistant-ui/react-ai-sdk";
+import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export default function Page() {
+  const chat = useChat({
+    api: "/api/chat",
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+  });
+  const runtime = useAISDKRuntime(chat);
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+Render the gate with a toolkit entry. The `approval` field carries the gate state, and `respondToApproval` is the only correct way to acknowledge it (it reads the approval id from the part):
+
+```tsx title="@/app/page.tsx"
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import {
+  AssistantRuntimeProvider,
+  Tools,
+  type Toolkit,
+  useAui,
+} from "@assistant-ui/react";
+import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
+import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
+import { Thread } from "@/components/assistant-ui/thread";
+
+const toolkit = {
+  deploy: {
+    type: "backend",
+    render: ({ args, approval, respondToApproval, result }) => {
+      if (approval?.approved === undefined) {
+        return (
+          <div>
+            <p>Approve deploy to {args.target}?</p>
+            <button onClick={() => respondToApproval({ approved: true })}>
+              Approve
+            </button>
+            <button
+              onClick={() =>
+                respondToApproval({ approved: false, reason: "user denied" })
+              }
+            >
+              Deny
+            </button>
+          </div>
+        );
+      }
+      if (approval?.approved === false) return <p>Denied</p>;
+      if (result === undefined) return <p>Approved, deploying…</p>;
+      return <p>Deployed {result.deployed}</p>;
+    },
+  },
+} satisfies Toolkit;
+
+export default function Page() {
+  const chat = useChat({
+    api: "/api/chat",
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+  });
+  const runtime = useAISDKRuntime(chat);
+  const aui = useAui({ tools: Tools({ toolkit }) });
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+See the [tool UI guide](/docs/tools/tool-ui#server-side-approval-gates) for the full three-state semantics of `approval.approved` and the `isAutomatic` flag.
+
 ## Quote context
 
 assistant-ui's composer can attach quote metadata to user messages (e.g. when the user selects text and clicks "Quote"). On the server, `injectQuoteContext` flattens that metadata into a markdown blockquote prefix so the LLM sees the quoted text:
@@ -491,6 +612,8 @@ const runtime = useAISDKRuntime(chat);
 
 [`examples/with-ai-sdk-v6`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6) shows a complete reference implementation.
 
+For responses that should survive a page reload mid-stream, see [Resumable streams](/docs/guides/resumable-streams), which wraps the same v6 byte stream in `assistant-stream/resumable`.
+
 ## Next
 
 <Cards>
@@ -504,4 +627,9 @@ const runtime = useAISDKRuntime(chat);
     description="Single-thread, AssistantCloud, custom thread list."
     href="/docs/runtimes/concepts/threads"
   />
+  <Card
+    title="Resumable streams"
+    description="Survive page reloads and connection drops mid-response."
+    href="/docs/guides/resumable-streams"
+  />
 </Cards>

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

@@ -287,6 +287,12 @@ A few invariants worth knowing when wiring a custom UI on top of `loadMore()`:
       description: "Persist title changes from the UI.",
       required: true,
     },
+    {
+      name: "updateCustom",
+      type: "(remoteId: string, custom: Record<string, unknown> | undefined) => Promise<void>",
+      description:
+        "Optional. Persist replacement custom metadata from `aui.threadListItem().updateCustom(custom)`.",
+    },
     {
       name: "archive",
       type: "(remoteId: string) => Promise<void>",
@@ -355,7 +361,7 @@ function ThreadListItemMeta() {
 }
 ```
 
-`custom` is preserved across `rename`, `archive`, `unarchive`, and `generateTitle`. To mutate it, return updated values from a subsequent `fetch()` or call `runtime.threads.reload()`.
+`custom` is preserved across `rename`, `archive`, `unarchive`, and `generateTitle`. To replace it from your UI, implement `RemoteThreadListAdapter.updateCustom` and call `aui.threadListItem().updateCustom(custom)`. The cloud adapter persists this through `cloud.threads.update(threadId, { metadata })`. If your adapter mutates thread metadata through a separate application path, return the updated values from `fetch()` or call `aui.threads().reload()` to re-run `list()`.
 
 ## ExternalStoreThreadListAdapter
 

package/.docs/raw/docs/runtimes/custom/data-stream.mdx

@@ -17,6 +17,17 @@ Pick this runtime when:
 
 If your backend exposes a richer state surface, consider [`AssistantTransport`](/docs/runtimes/custom/assistant-transport) instead.
 
+## Wire protocols
+
+`useDataStreamRuntime` accepts two wire formats via its `protocol` option:
+
+| Protocol | Default | Matching backend |
+| --- | --- | --- |
+| `"ui-message-stream"` | yes | AI SDK v6's `result.toUIMessageStreamResponse()` (SSE) |
+| `"data-stream"` | no | `createAssistantStreamResponse` from `assistant-stream`, or AI SDK v4's `toDataStreamResponse()` (Vercel data stream v1) |
+
+Pairing the default decoder with a data stream backend throws `Stream ended abruptly without receiving [DONE] marker` at flush; pass `protocol: "data-stream"` to switch decoders.
+
 ## Install
 
 <PlatformTabs>
@@ -55,7 +66,10 @@ import { AssistantRuntimeProvider } from "@assistant-ui/react";
 import { Thread } from "@/components/assistant-ui/thread";
 
 export default function ChatPage() {
-  const runtime = useDataStreamRuntime({ api: "/api/chat" });
+  const runtime = useDataStreamRuntime({
+    api: "/api/chat",
+    protocol: "data-stream",
+  });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <Thread />
@@ -76,7 +90,10 @@ import { Thread } from "@/components/assistant-ui/thread";
 const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
 
 export default function ChatPage() {
-  const runtime = useDataStreamRuntime({ api: `${API_URL}/api/chat` });
+  const runtime = useDataStreamRuntime({
+    api: `${API_URL}/api/chat`,
+    protocol: "data-stream",
+  });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <View style={{ flex: 1 }}>
@@ -99,6 +116,7 @@ import { Thread } from "./components/thread.js";
 export function App() {
   const runtime = useDataStreamRuntime({
     api: "http://localhost:3000/api/chat",
+    protocol: "data-stream",
   });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -139,6 +157,8 @@ export async function POST(request: Request) {
 
 The request body includes `messages`, `tools`, `system` (if configured), and `threadId`.
 
+`createAssistantStreamResponse` returns a standard Web `Response`. It drops into any Fetch-style route (Next.js App Router, Hono, Bun.serve, Deno, Cloudflare Workers) without ceremony. On frameworks that use their own response object (Express, Fastify), copy `status` and `headers` over, then pipe `response.body` into the framework's writable stream. Avoid sending the `Response` body into a `res` object whose lifecycle is already controlled by the framework (that is the `ERR_INVALID_STATE: Controller is already closed` failure mode).
+
 </Step>
 </Steps>
 
@@ -147,6 +167,7 @@ The request body includes `messages`, `tools`, `system` (if configured), and `th
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
+  protocol: "data-stream",
   headers: { Authorization: `Bearer ${token}`, "X-Custom-Header": "value" },
   credentials: "include",
 });
@@ -157,6 +178,7 @@ Evaluate per-request:
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
+  protocol: "data-stream",
   headers: async () => ({
     Authorization: `Bearer ${await getAuthToken()}`,
   }),
@@ -173,6 +195,7 @@ const runtime = useDataStreamRuntime({
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
+  protocol: "data-stream",
   onResponse: (response) => console.log("status:", response.status),
   onFinish: (message) => console.log("done:", message),
   onError: (error) => console.error(error),
@@ -207,6 +230,7 @@ const myTools = {
 
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
+  protocol: "data-stream",
   body: { tools: toToolsJSONSchema(myTools) },
 });
 ```
@@ -267,6 +291,7 @@ const runtime = useCloudRuntime({
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
+  protocol: "data-stream",
   initialMessages: [
     { role: "user", content: [{ type: "text", text: "Hello" }] },
     { role: "assistant", content: [{ type: "text", text: "Hi!" }] },

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

@@ -627,7 +627,15 @@ useExternalStoreRuntime({
     {
       name: "isDisabled",
       type: "boolean",
-      description: "Whether the chat input should be disabled.",
+      description:
+        "Disables the entire composer, including the text input. For a narrower gate that keeps the input usable but blocks only sending, use isSendDisabled.",
+      default: "false",
+    },
+    {
+      name: "isSendDisabled",
+      type: "boolean",
+      description:
+        "Blocks new-message sending while leaving the input usable. When true, the thread composer's canSend becomes false, the Send button is disabled, Enter and the steer hotkey are no-ops, and aui.composer().send() short-circuits. Edit composers (saving message edits) ignore this flag. Use this to gate sending on external React state (e.g. while tools or auth are still loading).",
       default: "false",
     },
     {

package/.docs/raw/docs/runtimes/custom/local-runtime.mdx

@@ -417,24 +417,35 @@ If you build the `content` array fresh from the current chunk each iteration, to
 
 `LocalRuntime` supports OpenAI-compatible function calling. Register tools through `useAui` so the runtime exposes them to your adapter via `context.tools`:
 
-```tsx
-import { useAui, Tools, type Toolkit } from "@assistant-ui/react";
+```tsx title="app/toolkit.tsx"
+"use generative";
+
+import { defineToolkit } from "@assistant-ui/react";
 import { z } from "zod";
 
-const myToolkit: Toolkit = {
+export default defineToolkit({
   getWeather: {
     description: "Get the current weather in a location",
     parameters: z.object({
       location: z.string(),
       unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
     }),
-    execute: async ({ location, unit }) => fetchWeather(location, unit),
+    execute: async ({ location, unit }) => {
+      "use client";
+      return fetchWeather(location, unit);
+    },
+    renderText: { running: "Checking the weather…", complete: "Weather ready" },
   },
-};
+});
+```
+
+```tsx title="app/MyRuntimeProvider.tsx"
+import { useAui, Tools } from "@assistant-ui/react";
+import toolkit from "./toolkit";
 
 function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   const runtime = useLocalRuntime(MyModelAdapter);
-  const aui = useAui({ tools: Tools({ toolkit: myToolkit }) });
+  const aui = useAui({ tools: Tools({ toolkit }) });
 
   return (
     <AssistantRuntimeProvider aui={aui} runtime={runtime}>
@@ -444,7 +455,7 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
-See the [tools guide](/docs/guides/tools) for advanced patterns.
+See the [tools guide](/docs/tools/defining-tools) for advanced patterns.
 
 ### Human-in-the-loop approval
 

package/.docs/raw/docs/runtimes/custom/overview.mdx

@@ -1,6 +1,6 @@
 ---
-title: Overview
-description: Four ways to wire assistant-ui to a backend without a framework adapter.
+title: Custom Runtime
+description: Build a React chat UI for any AI backend with assistant-ui — four runtime patterns covering local state, REST, custom protocols, and external runtimes.
 ---
 
 If no [framework adapter](/docs/runtimes/pick-a-runtime) fits your backend, this section gives you four building blocks. All four are built on one of the two core runtimes; understanding the layering (see [architecture](/docs/runtimes/concepts/architecture)) makes the choice clear.