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

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

@@ -196,7 +196,7 @@ type ThreadHistoryAdapter = {
 `load` runs when a thread opens. `append` runs after each message completes.
 
 <Callout type="info">
-`react-ai-sdk` requires `withFormat` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime in the AI SDK path. See the [AI SDK history docs](/docs/runtimes/ai-sdk/v6) for the full pattern.
+`react-ai-sdk` requires `withFormat` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime in the AI SDK path. See the [AI SDK history docs](/docs/runtimes/ai-sdk/v7) for the full pattern.
 </Callout>
 
 ## Suggestion adapter

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

@@ -118,7 +118,7 @@ The fastest path. Each adapter wraps one of the core or protocol layers and adds
 
 | Adapter | Layered on | Targets |
 | --- | --- | --- |
-| `react-ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v6 (`useChat`) |
+| `react-ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v7 (`useChat`) |
 | `react-langgraph` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/langgraph-sdk` |
 | `react-langchain` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/react`'s `useStream` |
 | `react-google-adk` | `ExternalStoreRuntime` | Google ADK JS or Python agents |

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

@@ -149,7 +149,7 @@ const adapterWithHistory: RemoteThreadListAdapter = {
     const history = useMemo<ThreadHistoryAdapter>(
       () => ({
         async load() {
-          const { remoteId } = aui.threadListItem().getState();
+          const { remoteId } = aui.threadListItem.getState();
           if (!remoteId) return { messages: [] };
           const rows = await fetch(
             `/api/threads/${remoteId}/messages`,
@@ -157,7 +157,7 @@ const adapterWithHistory: RemoteThreadListAdapter = {
           return { messages: rows.map(toThreadMessage) };
         },
         async append({ message, parentId }) {
-          const { remoteId } = await aui.threadListItem().initialize();
+          const { remoteId } = await aui.threadListItem.initialize();
           await fetch(`/api/threads/${remoteId}/messages`, {
             method: "POST",
             body: JSON.stringify({ message, parentId }),
@@ -181,11 +181,11 @@ const adapterWithHistory: RemoteThreadListAdapter = {
 
 ### Avoiding the first-message race
 
-`append` may be called before the thread record exists in your backend. Always await `aui.threadListItem().initialize()` before writing:
+`append` may be called before the thread record exists in your backend. Always await `aui.threadListItem.initialize()` before writing:
 
 ```ts
 async append({ message, parentId }) {
-  const { remoteId } = await aui.threadListItem().initialize();
+  const { remoteId } = await aui.threadListItem.initialize();
   await saveMessage(remoteId, parentId, message);
 }
 ```
@@ -194,14 +194,14 @@ async append({ message, parentId }) {
 
 ### Reloading after async authentication
 
-If your adapter depends on a user that resolves asynchronously (oidc, `next-auth`, `better-auth`), the initial `list()` may run before the user is available. Call `aui.threads().reload()` after auth completes:
+If your adapter depends on a user that resolves asynchronously (oidc, `next-auth`, `better-auth`), the initial `list()` may run before the user is available. Call `aui.threads.reload()` after auth completes:
 
 ```tsx
 function ReloadOnAuth() {
   const aui = useAui();
   const { isLoading, user } = useAuth();
   useEffect(() => {
-    if (!isLoading && user) aui.threads().reload();
+    if (!isLoading && user) aui.threads.reload();
   }, [isLoading, user?.id]);
   return null;
 }
@@ -211,7 +211,7 @@ function ReloadOnAuth() {
 
 ### 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.
+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.
 
 ```ts title="threadListAdapter.ts (excerpt)"
 async list({ after } = {}) {
@@ -271,7 +271,7 @@ A few invariants worth knowing when wiring a custom UI on top of `loadMore()`:
       name: "list",
       type: "(params?: { after?: string }) => Promise<{ threads: RemoteThreadMetadata[]; nextCursor?: string }>",
       description:
-        "Hydrate threads on mount. Each thread must include status and remoteId; title, externalId, and custom are optional. Return a `nextCursor` to enable `aui.threads().loadMore()`; the runtime will pass it back as `params.after` on the next call.",
+        "Hydrate threads on mount. Each thread must include status and remoteId; title, externalId, and custom are optional. Return a `nextCursor` to enable `aui.threads.loadMore()`; the runtime will pass it back as `params.after` on the next call.",
       required: true,
     },
     {
@@ -291,7 +291,7 @@ A few invariants worth knowing when wiring a custom UI on top of `loadMore()`:
       name: "updateCustom",
       type: "(remoteId: string, custom: Record<string, unknown> | undefined) => Promise<void>",
       description:
-        "Optional. Persist replacement custom metadata from `aui.threadListItem().updateCustom(custom)`.",
+        "Optional. Persist replacement custom metadata from `aui.threadListItem.updateCustom(custom)`.",
     },
     {
       name: "archive",
@@ -361,7 +361,7 @@ function ThreadListItemMeta() {
 }
 ```
 
-`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()`.
+`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/assistant-transport.mdx

@@ -536,8 +536,8 @@ function useResumeOnMount(threadId: string) {
         r.json(),
       );
       if (status.isRunning) {
-        const parentId = aui.thread().getState().messages.at(-1)?.id ?? null;
-        aui.thread().resumeRun({ parentId });
+        const parentId = aui.thread.getState().messages.at(-1)?.id ?? null;
+        aui.thread.resumeRun({ parentId });
       }
     })();
   }, [aui, threadId]);

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

@@ -19,14 +19,17 @@ If your backend exposes a richer state surface, consider [`AssistantTransport`](
 
 ## Wire protocols
 
-`useDataStreamRuntime` accepts two wire formats via its `protocol` option:
+`useDataStreamRuntime` accepts two wire formats. When `protocol` is omitted, it
+detects known Vercel AI response markers before falling back to UI message
+stream for compatibility.
 
-| Protocol | Default | Matching backend |
+| Protocol | Detection | 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) |
+| `"ui-message-stream"` | `x-vercel-ai-ui-message-stream: v1`, otherwise fallback | AI SDK v5+'s `result.toUIMessageStreamResponse()` (SSE) |
+| `"data-stream"` | `x-vercel-ai-data-stream: v1` | `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.
+Set `protocol` explicitly only for custom endpoints that do not preserve or
+expose the response marker.
 
 ## Install
 
@@ -66,10 +69,7 @@ import { AssistantRuntimeProvider } from "@assistant-ui/react";
 import { Thread } from "@/components/assistant-ui/thread";
 
 export default function ChatPage() {
-  const runtime = useDataStreamRuntime({
-    api: "/api/chat",
-    protocol: "data-stream",
-  });
+  const runtime = useDataStreamRuntime({ api: "/api/chat" });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <Thread />
@@ -90,10 +90,7 @@ 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`,
-    protocol: "data-stream",
-  });
+  const runtime = useDataStreamRuntime({ api: `${API_URL}/api/chat` });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <View style={{ flex: 1 }}>
@@ -116,7 +113,6 @@ 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}>
@@ -167,7 +163,6 @@ 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",
 });
@@ -178,7 +173,6 @@ Evaluate per-request:
 ```tsx
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
-  protocol: "data-stream",
   headers: async () => ({
     Authorization: `Bearer ${await getAuthToken()}`,
   }),
@@ -195,7 +189,6 @@ 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),
@@ -230,7 +223,6 @@ const myTools = {
 
 const runtime = useDataStreamRuntime({
   api: "/api/chat",
-  protocol: "data-stream",
   body: { tools: toToolsJSONSchema(myTools) },
 });
 ```
@@ -291,7 +283,6 @@ 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

@@ -741,7 +741,7 @@ useExternalStoreRuntime({
       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).",
+        "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",
     },
     {
@@ -796,7 +796,7 @@ useExternalStoreRuntime({
       name: "onResume",
       type: "(config: ResumeRunConfig) => Promise<void>",
       description:
-        "Handler for resuming an interrupted run (e.g. after a page reload mid-generation).",
+        "Handler for resuming an interrupted run (e.g. after a page reload mid-generation). For AI SDK reload-safe streaming, see the [Resumable Streams](/docs/guides/resumable-streams) guide.",
     },
     {
       name: "onResumeToolCall",

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

@@ -595,7 +595,7 @@ async function* createCustomStream(): AsyncGenerator<ChatModelRunResult> {
   };
 }
 
-aui.thread().resumeRun({
+aui.thread.resumeRun({
   parentId: "message-id",
   stream: createCustomStream,
 });
@@ -617,8 +617,8 @@ function useStreamReconnect(threadId: string) {
         r.json(),
       );
       if (status.isRunning) {
-        const parentId = aui.thread().getState().messages.at(-1)?.id ?? null;
-        aui.thread().resumeRun({ parentId });
+        const parentId = aui.thread.getState().messages.at(-1)?.id ?? null;
+        aui.thread.resumeRun({ parentId });
       }
     })();
   }, [aui, threadId]);
@@ -698,6 +698,8 @@ const OpenAIAdapter: ChatModelAdapter = {
 };
 ```
 
+For local development on a ChatGPT Plus or Pro plan, the same client can run without a real API key by pointing `baseURL` at a local OAuth proxy and passing a placeholder `apiKey`; see [ChatGPT Subscription](/docs/guides/chatgpt-subscription#openai-compatible-proxy).
+
 ### Custom REST API
 
 ```tsx

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

@@ -56,7 +56,7 @@ export default function Home() {
 - An Eve app mounted with `eve/next`.
 - A model credential for the model configured in `agent/agent.ts`.
 
-Eve's default gateway model ids route through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Use `AI_GATEWAY_API_KEY` or Vercel OIDC, or configure a direct provider `LanguageModel`.
+Eve's default gateway model ids route through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Use `AI_GATEWAY_API_KEY` or Vercel OIDC, or configure a direct provider `LanguageModel`. For local development, a direct `LanguageModel` can also run on a ChatGPT Plus or Pro plan without any API key; see [ChatGPT Subscription](/docs/guides/chatgpt-subscription).
 
 ## Install
 

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

@@ -5,7 +5,7 @@ description: Use LangChain's useStream hook with a React chat UI through assista
 
 import { LangGraphIcon } from "@/components/icons/langgraph";
 
-`@assistant-ui/react-langchain` wraps [`useStream`](https://docs.langchain.com/oss/javascript/langgraph-sdk/react-stream) from `@langchain/react` and exposes it as an assistant-ui runtime. It targets the same backend as [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph/overview) (LangGraph Cloud) but at a higher level, delegating stream plumbing to the upstream hook.
+`@assistant-ui/react-langchain` wraps [`useStream`](https://reference.langchain.com/javascript/langchain-react/use-stream) from `@langchain/react` and exposes it as an assistant-ui runtime. It targets the same backend as [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph/overview) (LangGraph Cloud) but at a higher level, delegating stream plumbing to the upstream hook.
 
 ## When to use it
 
@@ -32,7 +32,7 @@ Shared adapters (attachments, speech, feedback) work the same way described in [
 
 ## Requirements
 
-- A LangGraph Cloud API server (locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith)).
+- A LangGraph Cloud API server (locally via [LangGraph Studio](https://docs.langchain.com/langsmith/quick-start-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith)).
 - The graph state must include a `messages` key with LangChain-alike messages, or pass a custom `messagesKey`.
 
 ## Quickstart

package/.docs/raw/docs/runtimes/langgraph/agent-state.mdx

@@ -0,0 +1,181 @@
+---
+title: Agent state
+description: Read and optimistically update graph state with useLangGraphState and useLangGraphSetState in LangGraph.
+---
+
+`useLangGraphState` mirrors the graph's values object that LangGraph streams to the client. It updates live while the agent runs (when the `values` stream mode is enabled). `useLangGraphSetState` lets you apply optimistic local updates that ride the next send.
+
+## Enable the `values` stream mode
+
+<Callout type="warn">
+The default stream setup does **not** include the `values` stream mode. Without it, `useLangGraphState` never receives live graph state.
+</Callout>
+
+When you call `client.runs.stream` yourself, request `values` alongside the modes you already use:
+
+```ts
+client.runs.stream(threadId, assistantId, {
+  input,
+  streamMode: ["messages", "updates", "custom", "values"],
+});
+```
+
+If you use `unstable_createLangGraphStream`, its default stream modes do **not** include `values` either. Pass the option explicitly:
+
+```ts
+const stream = unstable_createLangGraphStream({
+  client,
+  assistantId: ASSISTANT_ID,
+  streamMode: ["messages", "updates", "custom", "values"],
+});
+```
+
+## Basic usage
+
+```tsx
+import {
+  useLangGraphState,
+  useLangGraphSetState,
+} from "@assistant-ui/react-langgraph";
+import { useAuiState } from "@assistant-ui/react";
+
+type GraphState = {
+  messages: unknown[];
+  filters: { region: string; maxResults: number };
+};
+
+const state = useLangGraphState<GraphState>();
+// state: GraphState | undefined  (latest agent state; updates live while the agent runs)
+
+const setState = useLangGraphSetState<GraphState>();
+// setState(next | (prev) => next)   (optimistic local update; sent with the NEXT run)
+
+const isRunning = useAuiState((s) => s.thread.isRunning);
+// isRunning: boolean                (whether the thread is currently running)
+```
+
+## Example
+
+Render graph state beside the chat and stage an optimistic filter update:
+
+```tsx
+"use client";
+
+import {
+  useLangGraphState,
+  useLangGraphSetState,
+} from "@assistant-ui/react-langgraph";
+import { useAuiState } from "@assistant-ui/react";
+import { Thread } from "@/components/assistant-ui/thread";
+
+type GraphState = {
+  filters: { region: string; maxResults: number };
+  lastQuery?: string;
+};
+
+export function CatalogAssistant() {
+  const state = useLangGraphState<GraphState>();
+  const setState = useLangGraphSetState<GraphState>();
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+
+  return (
+    <div className="flex h-full">
+      <aside className="w-72 border-r p-4">
+        <h2>Graph state</h2>
+        {state ? (
+          <ul>
+            <li>Region: {state.filters.region}</li>
+            <li>Max results: {state.filters.maxResults}</li>
+            {state.lastQuery && <li>Last query: {state.lastQuery}</li>}
+          </ul>
+        ) : (
+          <p>No graph state yet. Ensure streamMode includes "values".</p>
+        )}
+        <button
+          type="button"
+          disabled={isRunning}
+          onClick={() =>
+            setState((prev) => ({
+              ...prev,
+              filters: {
+                region: "eu",
+                maxResults: prev?.filters.maxResults ?? 10,
+              },
+            }))
+          }
+        >
+          Prefer EU region
+        </button>
+        {isRunning && <p>Agent is running…</p>}
+      </aside>
+      <main className="flex-1">
+        <Thread />
+      </main>
+    </div>
+  );
+}
+```
+
+The panel tracks the latest `values` events from the graph. The button updates the local overlay immediately; that update object is merged into the run `input` on the next send so LangGraph applies it through the graph's state reducers and input schema.
+
+## How state is synced
+
+LangGraph state is the graph's values object. When `streamMode` includes `"values"`, each `values` event updates the client-side snapshot that `useLangGraphState` exposes.
+
+The setter from `useLangGraphSetState` overlays that snapshot locally. On the next send, the runtime merges the update object into the run `input`, so LangGraph reduces it through the graph's state reducers and input schema.
+
+If you supply a custom `stream` callback, the staged update is available as `config.state`. Forward it into your run input yourself:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => {
+    const { externalId } = await initialize();
+    if (!externalId) throw new Error("Thread not found");
+
+    const client = createClient();
+    return client.runs.stream(externalId, ASSISTANT_ID, {
+      input: {
+        ...(config.state ?? {}),
+        messages,
+      },
+      streamMode: ["messages", "updates", "custom", "values"],
+    });
+  },
+});
+```
+
+The built-in path that uses the package helpers performs this merge for you. Custom `stream` callbacks must do it explicitly.
+
+## Write-back timing
+
+`useLangGraphSetState` is optimistic and local first. The value reaches the agent only when the next run starts. It is not a live channel into a run that is already in progress. Stage filters, preferences, or other graph fields that the next turn should apply through reducers; do not expect an in-flight run to observe mid-run setter calls.
+
+## Relationship to other state
+
+Keep the three state layers distinct:
+
+- **Your app state** stays yours (React state, URL, a store). assistant-ui does not own it.
+- **`useAuiState`** reads assistant-ui's client state (messages, composer, thread status).
+- **`useLangGraphState` / `useLangGraphSetState`** mirror state the **agent** (your LangGraph graph) owns, synced over the wire via `values` events.
+
+Use `useLangGraphState` and `useLangGraphSetState` for fields that live in the graph state schema. Use `useAuiState` for UI that depends on the chat thread itself. Use your own state for everything else.
+
+## Next
+
+<Cards>
+  <Card
+    title="Streaming"
+    description="Event handlers, message metadata, generative UI."
+    href="/docs/runtimes/langgraph/streaming"
+  />
+  <Card
+    title="Quickstart"
+    description="From-template and manual setup paths."
+    href="/docs/runtimes/langgraph/quickstart"
+  />
+  <Card
+    title="Generative UI"
+    description="Structured UI components emitted by your graph."
+    href="/docs/runtimes/langgraph/generative-ui"
+  />
+</Cards>

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

@@ -13,7 +13,7 @@ description: Build a chat UI for LangGraph agents in React with assistant-ui —
 
 Pick the LangGraph runtime when:
 
-- You have (or want) a LangGraph Cloud server, locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith).
+- You have (or want) a LangGraph Cloud server, locally via [LangGraph Studio](https://docs.langchain.com/langsmith/quick-start-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith).
 - Your graph state has a `messages` key with LangChain-alike messages.
 - You want generative UI (`ui_message`), per-message metadata, subgraph events, or checkpoint-based message editing.
 

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

@@ -9,7 +9,9 @@ OpenCode-specific React hooks for interacting with the running session. All hook
 
 ## Permissions
 
-OpenCode pauses tool execution to ask the user for permission (e.g. running shell commands, writing files). `useOpenCodePermissions` returns the pending permission requests and a reply function:
+OpenCode pauses tool execution to ask the user for permission (e.g. running shell commands, writing files). Permissions linked to a tool call are projected into assistant-ui's standard tool approval contract, so the default `ToolFallback` renders working **Allow**, **Always allow**, and **Deny** actions without a custom permission component. The always option only appears when OpenCode offers patterns to persist.
+
+`useOpenCodePermissions` remains available for custom tool renderers and permission requests that are not linked to a tool call. It returns the pending permission requests and a reply function:
 
 ```tsx
 import { useOpenCodePermissions } from "@assistant-ui/react-opencode";

package/.docs/raw/docs/tools/a2ui.mdx

@@ -0,0 +1,107 @@
+---
+title: A2UI over AG-UI
+description: Render A2UI surfaces from AG-UI activity snapshots as generative UI, using the community a2ui-surface convention.
+platforms: ["react"]
+---
+
+[A2UI](https://a2ui.org/) is a declarative generative UI protocol: the agent streams surface operations (create a surface, upsert components, update a data model) and the host renders them from a pre-approved component catalog, with no code over the wire. The AG-UI ecosystem carries A2UI as `ACTIVITY_SNAPSHOT` events with `activityType: "a2ui-surface"` and the operations under `content.a2ui_operations`; this is the convention emitted by [`@ag-ui/a2ui-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2ui-middleware).
+
+`useAgUiRuntime` consumes these snapshots natively. Each surface becomes one tool-call part with `toolCallId` `a2ui:<surfaceId>` and `toolName` `"present"`, whose args are the converted generative UI spec, so surfaces render through the same path as the [`present` frontend tool](/docs/tools/generative-ui). Snapshots with any other `activityType` are ignored, and the MCP Apps activity path is unaffected.
+
+## Wire contract
+
+A backend paints or updates a surface by emitting an activity snapshot on the AG-UI stream:
+
+```json
+{
+  "type": "ACTIVITY_SNAPSHOT",
+  "messageId": "a2ui-surface-call_1",
+  "activityType": "a2ui-surface",
+  "replace": true,
+  "content": {
+    "a2ui_operations": [
+      { "version": "v0.9", "createSurface": { "surfaceId": "s1" } },
+      {
+        "version": "v0.9",
+        "updateComponents": {
+          "surfaceId": "s1",
+          "components": [
+            { "id": "root", "component": "Card", "title": "Order", "children": ["total"] },
+            { "id": "total", "component": "Text", "text": { "path": "/total" } }
+          ]
+        }
+      },
+      {
+        "version": "v0.9",
+        "updateDataModel": { "surfaceId": "s1", "path": "/", "contents": { "total": "$42" } }
+      }
+    ]
+  }
+}
+```
+
+- A snapshot with `replace: true` (the schema default) rebuilds that `messageId`'s surface state from the operations it carries. `replace: false` means the snapshot is ignored when that `messageId` has already been seen, matching the AG-UI event spec. The middleware always emits `replace: true`.
+- Surfaces are keyed by the `surfaceId` inside the operations, not by `messageId`. Multiple snapshots that share a `messageId` update their surfaces in place, and the synthesized part keeps its `toolCallId`, so the rendered surface updates without duplicating parts.
+- Component trees use the A2UI adjacency-list model: nodes reference children by id, the root node has id `root`, and props of shape `{ "path": "/x/y" }` are JSON Pointer bindings resolved against the surface data model. Both v0.9 and v1.0 operation payloads are accepted, including the v1.0 inline `components` and `dataModel` on `createSurface`.
+- Lifecycle snapshots that carry a `status` (such as `"building"`) but no `a2ui_operations` are tolerated and produce no part until operations arrive. A `deleteSurface` operation removes the surface's part.
+- The `a2ui:` tool-call id prefix is reserved for synthesized surface parts: they are client-side render artifacts and are excluded from the history sent back to the agent, so genuine agent tool calls must not use ids starting with `a2ui:`.
+
+## Quick start
+
+Register the `present` frontend tool from `@assistant-ui/react-generative-ui`; incoming surfaces then render with the default vocabulary:
+
+```tsx
+import {
+  JSONGenerativeUI,
+  defaultGenerativeUILibrary,
+} from "@assistant-ui/react-generative-ui";
+
+const generative = new JSONGenerativeUI({
+  library: defaultGenerativeUILibrary,
+});
+
+const toolkit = {
+  present: generative.present({ display: "standalone" }),
+};
+```
+
+Pass the toolkit to your assistant as on the [Generative UI](/docs/tools/generative-ui) page; no other configuration is needed on `useAgUiRuntime`.
+
+## Actions
+
+`Button` nodes dispatch `$action` objects with type `"a2ui:action"` through the action registry. Wire the registry to `useAgUiSendA2uiAction` inside a component; the hook returns a stable function, so the toolkit can be memoized on it:
+
+```tsx
+import { useMemo } from "react";
+import { useAgUiSendA2uiAction } from "@assistant-ui/react-ag-ui";
+import {
+  JSONGenerativeUI,
+  createActionRegistry,
+  defaultGenerativeUILibrary,
+} from "@assistant-ui/react-generative-ui";
+
+function useA2uiToolkit() {
+  const sendA2uiAction = useAgUiSendA2uiAction();
+  return useMemo(() => {
+    const generative = new JSONGenerativeUI({
+      library: defaultGenerativeUILibrary,
+      actions: createActionRegistry({
+        "a2ui:action": ({ payload }) => sendA2uiAction(payload),
+      }),
+    });
+    return { present: generative.present({ display: "standalone" }) };
+  }, [sendA2uiAction]);
+}
+```
+
+Sending an action triggers a run with no new user message, and the agent receives it as `forwardedProps.a2uiAction.userAction`, the convention `@ag-ui/a2ui-middleware` consumes. The action rides exactly one run; the `type` field is stripped and a `timestamp` is added when absent.
+
+The middleware turns the action into a synthetic `log_a2ui_event` tool-call pair that is never declared in `input.tools`; a backend that validates tool calls against the declared tool list will reject it.
+
+## Component mapping
+
+The converter maps the A2UI basic catalog onto the default generative UI vocabulary: `Text` becomes `Markdown` (`h1` to `h6` variants become `Header`, `caption` becomes `Caption`), `Column` becomes `Col`, `TextField` becomes `Input` (the control name is derived from the last segment of its binding path), `CheckBox` becomes `Checkbox`, and `Image`, `Row`, `Card`, `Divider`, `Button` map one to one. A node with template children expands into a `ListView` over the bound list. `Button` actions become `$action` objects with type `"a2ui:action"` carrying the action name, `surfaceId`, and `sourceComponentId`, which is how your action registry receives them. Unknown components and operations are skipped with a debug warning, and conversion is bounded (depth 32, 100 template items, 5000 nodes) so a malformed stream cannot hang the client.
+
+## Limitations
+
+- The upstream middleware currently emits v0.9 operation payloads; the renderer accepts v0.9 and v1.0 shapes.

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

@@ -13,6 +13,8 @@ For authoring tools, see [Defining Tools](/docs/tools/defining-tools). For MCP s
 `@assistant-ui/react-ai-sdk` posts `{ messages, system, tools }` to your route. `tools` is the map of **frontend** tools the client serialized for this request (the model needs their schemas to call them, even though they run in the browser):
 
 ```ts
+import type { FrontendTools } from "@assistant-ui/react-ai-sdk";
+
 const {
   messages,
   system,
@@ -20,7 +22,7 @@ const {
 }: {
   messages: UIMessage[];
   system?: string;
-  tools?: Record<string, { description?: string; parameters: JSONSchema7 }>;
+  tools?: FrontendTools;
 } = await req.json();
 ```
 
@@ -136,9 +138,10 @@ To let the model see a frontend tool's result and continue, configure the runtim
 import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
 
 const runtime = useChatRuntime({
-  api: "/api/chat",
   sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
 });
 ```
 
-For the full AI SDK v6 backend setup — history persistence, reasoning, server-side approvals — see the [AI SDK v6 guide](/docs/runtimes/ai-sdk/v6).
+`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
+
+For the full AI SDK v7 backend setup — history persistence, reasoning, server-side approvals — see the [AI SDK v7 guide](/docs/runtimes/ai-sdk/v7).