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

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

@@ -17,14 +17,44 @@ If you do not have an existing store, use [`LocalRuntime`](/docs/runtimes/custom
 
 ## Architecture
 
-```mermaid
-graph TD
+<Flow.Root
+  llm={`graph TD
     A[Your state] -->|messages| B[ExternalStoreAdapter]
     B --> C[ExternalStoreRuntime]
     C --> D[assistant-ui components]
     D -->|user actions| B
-    B -->|state updates| A
-```
+    B -->|state updates| A`}
+>
+  <Flow.Canvas
+    className="pr-44"
+    edges={[
+      {
+        from: "components",
+        to: "adapter",
+        route: "loop-right",
+        label: "user actions",
+        laneOffset: 40,
+      },
+      {
+        from: "adapter",
+        to: "state",
+        route: "loop-right",
+        label: "state updates",
+        laneOffset: 88,
+      },
+    ]}
+  >
+    <Flow.Column>
+      <Flow.Node flowId="state">Your state</Flow.Node>
+      <Flow.Arrow direction="down" label="messages" length={36} />
+      <Flow.Node flowId="adapter">ExternalStoreAdapter</Flow.Node>
+      <Flow.Arrow direction="down" length={36} />
+      <Flow.Node>ExternalStoreRuntime</Flow.Node>
+      <Flow.Arrow direction="down" length={36} />
+      <Flow.Node flowId="components">assistant-ui components</Flow.Node>
+    </Flow.Column>
+  </Flow.Canvas>
+</Flow.Root>
 
 Key idea: you own the state, the adapter translates between your format and assistant-ui's. UI features are capability-based; if you provide `setMessages`, branching turns on; if you provide `onEdit`, editing turns on; etc.
 
@@ -178,6 +208,7 @@ Each handler enables a specific UI feature.
 | `onReload` | Regenerate button |
 | `onCancel` | Cancel button while generating |
 | `onAddToolResult` | Client-side tool result handoff |
+| `queue` | Queueing messages sent while a run is in progress |
 
 ## Streaming responses
 
@@ -312,6 +343,33 @@ const runtime = useExternalStoreRuntime({
 });
 ```
 
+## Queueing messages during a run
+
+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()`).
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import { createMessageQueue, useExternalStoreRuntime } from "@assistant-ui/react";
+
+const [queue] = useState(() => createMessageQueue({ run: onNew }));
+
+const runtime = useExternalStoreRuntime({
+  messages,
+  isRunning,
+  onNew,
+  queue: queue.adapter,
+});
+
+const wasRunning = useRef(isRunning);
+useEffect(() => {
+  if (!wasRunning.current && isRunning) queue.notifyBusy();
+  if (wasRunning.current && !isRunning) queue.notifyIdle();
+  wasRunning.current = isRunning;
+}, [isRunning, queue]);
+```
+
 ## 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.

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

@@ -457,18 +457,122 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 
 See the [tools guide](/docs/tools/defining-tools) for advanced patterns.
 
-### Human-in-the-loop approval
+### Human-in-the-loop tools
 
-Require user confirmation before specific tools execute:
+Tools listed in `unstable_humanToolNames` are not executed by code. The run pauses on the tool call and the user supplies the result through the tool UI:
 
 ```ts
 const runtime = useLocalRuntime(MyModelAdapter, {
-  unstable_humanToolNames: ["delete_file", "send_email"],
+  unstable_humanToolNames: ["send_email"],
+});
+```
+
+The pause is driven by the message status your adapter returns; `LocalRuntime` never sets it for you. When the model requests a human tool call, end the run with `status: { type: "requires-action", reason: "tool-calls" }`. Without that status, the runtime marks the message complete and nothing waits. Only return it while a listed tool call is missing its result: unresolved tool calls that are not listed do not hold the run, so the runtime would invoke your adapter again immediately.
+
+```tsx
+const MyModelAdapter: ChatModelAdapter = {
+  async run({ messages, abortSignal, unstable_getMessage }) {
+    const toolResults = unstable_getMessage().content.flatMap((part) =>
+      part.type === "tool-call" && part.result !== undefined
+        ? [{ toolCallId: part.toolCallId, result: part.result }]
+        : [],
+    );
+
+    const result = await fetch("<YOUR_API_ENDPOINT>", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ messages, toolResults }),
+      signal: abortSignal,
+    });
+    const data = await result.json();
+
+    if (data.toolCall) {
+      return {
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: data.toolCall.id,
+            toolName: data.toolCall.name,
+            args: data.toolCall.args,
+            argsText: JSON.stringify(data.toolCall.args),
+          },
+        ],
+        status: { type: "requires-action", reason: "tool-calls" },
+      };
+    }
+
+    return { content: [{ type: "text", text: data.text }] };
+  },
+};
+```
+
+The full loop:
+
+1. **The run pauses.** While a listed tool call has no result, the runtime stops invoking your adapter. The unresolved tool call part reports `status.type === "requires-action"` to its renderer.
+2. **The user responds.** The tool UI completes the call with `addResult(...)`. The stock [`ToolFallback`](/docs/ui/tool-fallback) component handles this out of the box: in the requires-action state it shows Allow and Deny buttons that record the decision as the tool result.
+3. **The run resumes.** Once every listed tool call has a result, the runtime invokes your adapter again. The resumed call receives the same `messages` array as before (it ends at the user message; the in-progress assistant message is not part of it), so read the recorded results from `unstable_getMessage().content` as shown above. Content returned by the resumed call is appended to the same assistant message.
+
+For a custom confirmation UI, register a human tool whose `render` completes the call with `addResult`. The shape of the result payload is yours to define; the adapter receives it verbatim and translates it for your backend:
+
+```tsx
+const toolkit = defineToolkit({
+  send_email: {
+    type: "human",
+    description: "Send an email after the user confirms",
+    parameters: z.object({ to: z.string(), subject: z.string() }),
+    render: ({ args, result, addResult }) => {
+      if (result) {
+        return <p>{result.approved ? "Sent" : `Cancelled: ${result.reason}`}</p>;
+      }
+      return (
+        <div>
+          <p>
+            Send "{args.subject}" to {args.to}?
+          </p>
+          <button onClick={() => addResult({ approved: true })}>Allow</button>
+          <button
+            onClick={() =>
+              addResult({ approved: false, reason: "User declined" })
+            }
+          >
+            Deny
+          </button>
+        </div>
+      );
+    },
+  },
 });
 ```
 
 `unstable_humanToolNames` is unstable; see [stability](/docs/runtimes/concepts/stability).
 
+### Approval gates
+
+The [server-side approval gate](/docs/tools/tool-ui#server-side-approval-gates) is also supported on `LocalRuntime`, for actions your backend executes after the user authorizes them. Where a human tool asks the user to supply the tool result, an approval gate asks the user to allow or block an action the adapter performs. Emit `approval: { id }` on the tool call part and end the run with the same `requires-action` status:
+
+```tsx
+return {
+  content: [
+    {
+      type: "tool-call",
+      toolCallId: data.toolCall.id,
+      toolName: data.toolCall.name,
+      args: data.toolCall.args,
+      argsText: JSON.stringify(data.toolCall.args),
+      approval: { id: data.toolCall.id },
+    },
+  ],
+  status: { type: "requires-action", reason: "tool-calls" },
+};
+```
+
+A tool call with a pending approval pauses the run, whether or not the tool is listed in `unstable_humanToolNames`. Always emit gates in the pending state (`approval: { id }` with no `approved` field); a part that arrives already decided is treated as resolved and the runtime invokes the adapter again immediately. The stock [`ToolFallback`](/docs/ui/tool-fallback) Allow and Deny buttons, or a custom renderer calling `respondToApproval({ approved, reason? })`, record the decision:
+
+- **Deny** sets `approval.approved: false` and synthesizes an error result (`{ error: reason || "Tool approval denied" }` with `isError: true`), so the model sees the denial.
+- **Allow** sets `approval.approved: true` and leaves the result empty; performing the action is your adapter's job.
+
+Once every pending approval on the message is decided and every listed human tool has a result, the runtime invokes your adapter again. Read the decisions from `unstable_getMessage().content`, perform the approved actions, and return the follow-up response. A tool call that carries an approval is owned by the gate: it does not additionally require a result, even when its name is listed in `unstable_humanToolNames`.
+
 ## Resuming a run
 
 `resumeRun` reconnects to an in-progress assistant run. Useful for page refresh, network reconnect, tab backgrounding, or thread switching when the backend is still generating.
@@ -521,6 +625,18 @@ function useStreamReconnect(threadId: string) {
 }
 ```
 
+## Queueing messages during a run
+
+Set `unstable_enableMessageQueue` to keep the composer usable while a run is in progress. A message sent during a run is held in `composer.queue` and sent once the run settles; steering a queued message runs it next.
+
+```tsx
+const runtime = useLocalRuntime(MyModelAdapter, {
+  unstable_enableMessageQueue: true,
+});
+```
+
+Render the pending messages with [`ComposerPrimitive.Queue`](/docs/api-reference/primitives/composer) and [`QueueItemPrimitive`](/docs/api-reference/primitives/queue-item).
+
 ## Adapters
 
 Attachments, speech, feedback, history, and suggestions are wired through the standard adapter contracts, see [adapters](/docs/runtimes/concepts/adapters):
@@ -731,7 +847,7 @@ const CustomAPIAdapter: ChatModelAdapter = {
       name: "unstable_humanToolNames",
       type: "string[]",
       description:
-        "Tool names that require human approval before execution (unstable).",
+        "Tool names that pause the run until the user supplies a result via addResult (unstable).",
     },
   ]}
 />

package/.docs/raw/docs/runtimes/google-adk/hooks.mdx

@@ -389,8 +389,8 @@ Register the renderer with a backend toolkit entry inside `AssistantRuntimeProvi
 ```tsx
 import {
   AssistantRuntimeProvider,
+  defineToolkit,
   Tools,
-  type Toolkit,
   useAui,
 } from "@assistant-ui/react";
 import {
@@ -399,12 +399,12 @@ import {
 } from "@assistant-ui/react-google-adk";
 import { Thread } from "@/components/assistant-ui/thread";
 
-const toolkit = {
+const toolkit = defineToolkit({
   adk_request_input: {
     type: "backend",
     render: RequestInputToolUI,
   },
-} satisfies Toolkit;
+});
 
 function App() {
   const runtime = useAdkRuntime({
@@ -426,8 +426,8 @@ function App() {
 ```tsx
 import {
   AssistantRuntimeProvider,
+  defineToolkit,
   Tools,
-  type Toolkit,
   useAui,
 } from "@assistant-ui/react-native";
 import {
@@ -439,12 +439,12 @@ import { Thread } from "@/components/assistant-ui/thread";
 
 const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
 
-const toolkit = {
+const toolkit = defineToolkit({
   adk_request_input: {
     type: "backend",
     render: RequestInputToolUI,
   },
-} satisfies Toolkit;
+});
 
 function App() {
   const runtime = useAdkRuntime({
@@ -468,8 +468,8 @@ function App() {
 ```tsx
 import {
   AssistantRuntimeProvider,
+  defineToolkit,
   Tools,
-  type Toolkit,
   useAui,
 } from "@assistant-ui/react-ink";
 import {
@@ -479,12 +479,12 @@ import {
 import { Box } from "ink";
 import { Thread } from "./components/thread.js";
 
-const toolkit = {
+const toolkit = defineToolkit({
   adk_request_input: {
     type: "backend",
     render: RequestInputToolUI,
   },
-} satisfies Toolkit;
+});
 
 function App() {
   const runtime = useAdkRuntime({

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

@@ -106,6 +106,19 @@ LangGraph can emit structured UI components alongside assistant messages via `pu
 
 See [Generative UI](/docs/runtimes/langgraph/generative-ui) for full setup: enabling the `custom` stream channel, emitting UI messages, registering renderers, dynamic loading, and persisting UI state across thread switches.
 
+## Queueing messages during a run
+
+Set `unstable_enableMessageQueue` to keep the composer usable while a run is streaming. A message sent during a run is held in `composer.queue` and sent once the run settles; steering a queued message runs it next.
+
+```tsx
+const runtime = useLangGraphRuntime({
+  stream,
+  unstable_enableMessageQueue: true,
+});
+```
+
+Render the pending messages with [`ComposerPrimitive.Queue`](/docs/api-reference/primitives/composer) and [`QueueItemPrimitive`](/docs/api-reference/primitives/queue-item).
+
 ## Next
 
 <Cards>

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-2.mdx

@@ -94,14 +94,14 @@ This simply displays the tool name and arguments passed to it, but not the resul
 
 import { Thread } from "@/components/assistant-ui/thread";
 import { PriceSnapshotToolUI } from "@/components/tools/price-snapshot/PriceSnapshotTool";
-import { AuiProvider, Tools, type Toolkit, useAui } from "@assistant-ui/react";
+import { AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
 
-const toolkit = {
+const toolkit = defineToolkit({
   price_snapshot: {
     type: "backend",
     render: PriceSnapshotToolUI,
   },
-} satisfies Toolkit;
+});
 
 export default function Home() {
   const aui = useAui({ tools: Tools({ toolkit }) });
@@ -326,12 +326,12 @@ export const ToolFallback: ToolCallMessagePartComponent = ({
 ### Bind fallback UI
 
 ```tsx title="@/app/page.tsx"
-const toolkit = {
+const toolkit = defineToolkit({
   price_snapshot: {
     type: "backend",
     render: PriceSnapshotToolUI,
   },
-} satisfies Toolkit;
+});
 
 export default function Home() {
   const aui = useAui({ tools: Tools({ toolkit }) });

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-3.mdx

@@ -212,9 +212,9 @@ export function TransactionConfirmationPending(props: TransactionConfirmation) {
 import { Thread } from "@/components/assistant-ui/thread";
 import { PriceSnapshotToolUI } from "@/components/tools/price-snapshot/PriceSnapshotTool";
 import { PurchaseStockToolUI } from "@/components/tools/purchase-stock/PurchaseStockTool";
-import { AuiProvider, Tools, type Toolkit, useAui } from "@assistant-ui/react";
+import { AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
 
-const toolkit = {
+const toolkit = defineToolkit({
   price_snapshot: {
     type: "backend",
     render: PriceSnapshotToolUI,
@@ -223,7 +223,7 @@ const toolkit = {
     type: "backend",
     render: PurchaseStockToolUI,
   },
-} satisfies Toolkit;
+});
 
 export default function Home() {
   const aui = useAui({ tools: Tools({ toolkit }) });

package/.docs/raw/docs/runtimes/pick-a-runtime.mdx

@@ -28,13 +28,13 @@ assistant-ui ships React adapter packages for these. Pick the matching card and
     icon={<VercelIcon width={20} height={20} />}
     title="Vercel AI SDK"
     description="useChat hook, streaming, tools, attachments, multi-step. v6 current; v5 / v4 legacy."
-    href="/docs/runtimes/ai-sdk"
+    href="/docs/runtimes/ai-sdk/overview"
   />
   <Card
     icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
     title="LangGraph"
     description="Direct integration with @langchain/langgraph-sdk. Subgraph events, UI messages, message metadata."
-    href="/docs/runtimes/langgraph"
+    href="/docs/runtimes/langgraph/overview"
   />
   <Card
     icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
@@ -46,7 +46,7 @@ assistant-ui ships React adapter packages for these. Pick the matching card and
     icon={<AdkIcon width={20} height={20} />}
     title="Google ADK"
     description="ADK JS or Python agents. Tool confirmations, auth flows, multi-agent, code execution."
-    href="/docs/runtimes/google-adk"
+    href="/docs/runtimes/google-adk/overview"
   />
   <Card
     icon={<A2AIcon width={20} height={20} />}
@@ -58,14 +58,14 @@ assistant-ui ships React adapter packages for these. Pick the matching card and
     icon={<AguiIcon width={20} height={20} />}
     title="AG-UI Protocol"
     description="AG-UI agents (CopilotKit, custom servers). Streaming text, thinking, tool calls, state snapshots."
-    href="/docs/runtimes/ag-ui"
+    href="/docs/runtimes/ag-ui/overview"
   />
   <PlatformOnly platforms={["react"]}>
     <Card
       icon={<OpenCodeIcon width={20} height={20} />}
       title="OpenCode"
       description="OpenCode coding-agent server. Permission flows, questions, fork / revert. Experimental."
-      href="/docs/runtimes/opencode"
+      href="/docs/runtimes/opencode/overview"
     />
   </PlatformOnly>
 </Cards>
@@ -104,7 +104,7 @@ If you do not know your framework yet, or your backend is custom, pick by what y
 | Backend that already speaks the data stream protocol | [DataStream](/docs/runtimes/custom/data-stream) |
 | Stream full agent state snapshots (not just messages) | [AssistantTransport](/docs/runtimes/custom/assistant-transport) |
 
-If none of the framework adapters fits, start at [custom backend](/docs/runtimes/custom).
+If none of the framework adapters fits, start at [custom backend](/docs/runtimes/custom/overview).
 
 ## Shared concepts
 

package/.docs/raw/docs/tools/backend.mdx

@@ -1,6 +1,6 @@
 ---
 title: Backend Tools
-description: Wire assistant-ui toolkits into your server with the AI SDK — generativeTools, frontendTools, mixing client and server tools, and multi-modal results.
+description: Wire assistant-ui toolkits into your server with the AI SDK — AISDKToolkit, frontendTools, mixing client and server tools, and multi-modal results.
 platforms: ["react"]
 ---
 
@@ -24,16 +24,18 @@ const {
 } = await req.json();
 ```
 
-## Generative toolkits: `generativeTools`
+## Generative toolkits: `AISDKToolkit`
 
-When you author tools in a [`"use generative"` file](/docs/tools/defining-tools#quick-start-use-generative), the same import resolves to the **server build** inside a route handler — schema plus any backend `execute`, with renderers stripped. Pass it to `generativeTools` together with the uploaded `tools`:
+When you author tools in a [`"use generative"` file](/docs/tools/defining-tools#quick-start-use-generative), the same import resolves to the **server build** inside a route handler — schema plus any backend `execute`, with renderers stripped. Wrap it in an `AISDKToolkit` and call `.tools()` with the uploaded `tools`:
 
 ```ts title="app/api/chat/route.ts"
-import { generativeTools } from "@assistant-ui/react-ai-sdk";
+import { AISDKToolkit } from "@assistant-ui/react-ai-sdk";
 import { streamText, convertToModelMessages, type UIMessage } from "ai";
 import { openai } from "@ai-sdk/openai";
 import toolkit from "../../toolkit";
 
+const aiToolkit = new AISDKToolkit({ toolkit });
+
 export async function POST(req: Request) {
   const { messages, system, tools } = await req.json();
 
@@ -41,24 +43,29 @@ export async function POST(req: Request) {
     model: openai("gpt-5.4-nano"),
     system,
     messages: await convertToModelMessages(messages),
-    tools: generativeTools({ toolkit, frontendTools: tools }),
+    tools: await aiToolkit.tools({ frontend: tools }),
   });
 
   return result.toUIMessageStreamResponse();
 }
 ```
 
-`generativeTools` registers every toolkit tool with the model using its schema, wires the backend `execute` where the server build carries one, and merges in the uploaded `frontendTools`. A server `execute` wins over an uploaded entry of the same name. Frontend and human tools (no server `execute`) are exposed schema-only and left for the client and the user to fulfill.
+`AISDKToolkit.tools()` registers every toolkit tool with the model using its schema, wires the backend `execute` where the server build carries one, and merges in the uploaded frontend tools. A server `execute` wins over an uploaded entry of the same name. Frontend and human tools (no server `execute`) are exposed schema-only and left for the client and the user to fulfill.
 
 <Callout type="info">
-  If your toolkit spreads in MCP server tools (`defineMcpToolkit`), use
-  `new AISDKToolkit({ toolkit }).tools({ frontend })` instead of
-  `generativeTools` — it also opens the MCP connections. See [MCP](/docs/tools/mcp).
+  If your toolkit spreads in MCP server tools (`defineMcpToolkit`), `.tools()`
+  also opens those connections. A module-scope `aiToolkit` pools them across
+  requests; see [MCP](/docs/tools/mcp) for the connection lifecycle and when to
+  call `aiToolkit.close()`. The older
+  `generativeTools({ toolkit, frontendTools })` is deprecated, MCP-less, and
+  superseded by `AISDKToolkit`.
 </Callout>
 
 ## Client-defined tools: `frontendTools`
 
-If you don't use the generative compiler — for example a plain [`satisfies Toolkit`](/docs/tools/defining-tools#render-only-tools-for-externally-executed-tools) with browser-executed tools — the AI SDK adapter still serializes those tools into the request `tools`. Convert them to the AI SDK shape with `frontendTools` and spread your own server tools alongside:
+If a toolkit cannot go through the generative compiler, the AI SDK adapter still
+serializes browser-executed tools into the request `tools`. Convert them to the
+AI SDK shape with `frontendTools` and spread your own server tools alongside:
 
 ```ts title="app/api/chat/route.ts"
 import { frontendTools } from "@assistant-ui/react-ai-sdk";
@@ -86,7 +93,8 @@ export async function POST(req: Request) {
 }
 ```
 
-`generativeTools` calls `frontendTools` for you under the hood; reach for `frontendTools` directly when you're not on the generative build.
+`AISDKToolkit.tools()` calls `frontendTools` for you under the hood; reach for
+`frontendTools` directly when you're not on the generative build.
 
 <Callout type="tip">
   `toToolsJSONSchema` emits the uploaded tools in alphabetical order, so two