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

package/.docs/raw/docs/guides/input-history.mdx

@@ -0,0 +1,55 @@
+---
+title: Input History
+description: Terminal-style ArrowUp/ArrowDown recall of previously sent messages in the assistant-ui React composer.
+platforms: ["react"]
+---
+
+Input history lets users press ArrowUp in an empty composer to recall previously sent messages, newest first, like a shell prompt. ArrowDown steps back toward the newest entry and finally restores the draft that was being typed when browsing started.
+
+<Callout type="warn">
+  This API is marked unstable and may change without notice.
+</Callout>
+
+## Usage
+
+Spread the hook's bundle onto `ComposerPrimitive.Input`:
+
+```tsx
+import {
+  ComposerPrimitive,
+  unstable_useComposerInputHistory,
+} from "@assistant-ui/react";
+
+const Composer = () => {
+  const history = unstable_useComposerInputHistory();
+
+  return (
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input {...history} />
+      <ComposerPrimitive.Send />
+    </ComposerPrimitive.Root>
+  );
+};
+```
+
+The history ring is derived live from the current thread's user messages (trimmed, with adjacent duplicates collapsed), so it needs no persistence or configuration.
+
+## Behavior
+
+- ArrowUp starts recall only when the composer is empty (whitespace-only drafts count as empty and are restored on the way back down).
+- While a recalled multi-line message is shown, arrows move the caret line by line; recall only steps when the caret is on the first line (ArrowUp) or last line (ArrowDown).
+- An open mention or slash-command popover keeps owning the arrow keys; the hook yields whenever a trigger popover is active.
+- IME composition, modifier keys, text selections, and events a preceding handler already `preventDefault`ed are left untouched.
+- Switching threads or sending a message resets the browse position.
+- The hook is inert on edit composers.
+
+To interleave your own ArrowUp handling ahead of history (for example, stepping through queued messages), compose your handler before the hook's and call `preventDefault` when you consume the key:
+
+```tsx
+<ComposerPrimitive.Input
+  onKeyDown={(e) => {
+    myHandler(e);
+    history.onKeyDown(e);
+  }}
+/>
+```

package/.docs/raw/docs/guides/virtualization.mdx

@@ -0,0 +1,63 @@
+---
+title: Thread Virtualization
+description: Render very long threads with @tanstack/react-virtual and ThreadPrimitive.MessageByIndex.
+platforms: ["react"]
+---
+
+Virtualization mounts only the messages near the viewport and represents the rest as empty space, so a thread with thousands of messages scrolls like one with twenty. assistant-ui does not ship a virtualized thread component; this guide shows the supported composition, extracted from a production consumer and available as a runnable example: [`examples/with-virtualized-thread`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-virtualized-thread).
+
+## Do you need this?
+
+Probably not. The default kit already renders message bodies with `content-visibility: auto` and `contain-intrinsic-size`, which skips paint work for off-screen messages, and `ThreadPrimitive.Viewport` handles auto-scroll. That covers typical threads. Reach for virtualization when React mount and update cost itself becomes the bottleneck: threads with hundreds to thousands of messages, or very heavy per-message content, where typing latency degrades because every message stays mounted.
+
+## Rendering messages by index
+
+`ThreadPrimitive.MessageByIndex` renders a single message at a given index and memoizes on the index plus per-field `components` identity. Pass a module-level components object so the memo holds and a streaming delta only re-renders the message it belongs to:
+
+```tsx
+const MESSAGE_COMPONENTS = { UserMessage, AssistantMessage };
+
+<ThreadPrimitive.MessageByIndex index={index} components={MESSAGE_COMPONENTS} />;
+```
+
+## Grouping into turns
+
+Virtualizing per user turn (a user message plus the responses that follow it) gives the virtualizer stable, meaningfully sized items. Subscribe to a single signature string so the selector returns a primitive and the turn array only rebuilds when membership actually changes:
+
+```tsx
+const signature = useAuiState((s) =>
+  s.thread.messages.map((m, i) => `${i}:${m.role}:${m.id}`).join("\n"),
+);
+const turns = useMemo(() => buildTurns(signature), [signature]);
+```
+
+## Padding spacers, not absolute positioning
+
+Render the virtual items in normal document flow inside a spacer div whose `paddingTop`/`paddingBottom` represent the unmounted regions. Items remain regular flow children, so message CSS (including `position: sticky` patterns and the kit styling) keeps working, and `virtualizer.measureElement` records real heights as items mount:
+
+```tsx
+const items = virtualizer.getVirtualItems();
+const paddingTop = items[0]?.start ?? 0;
+const paddingBottom = Math.max(
+  0,
+  virtualizer.getTotalSize() - (items.at(-1)?.end ?? 0),
+);
+```
+
+## Owning the scroll element
+
+The composition owns its scroll container instead of using `ThreadPrimitive.Viewport`: the built-in auto-scroll assumes every message is mounted, and its resize-driven re-pin can fight the virtualizer's measurement adjustments. Three pieces replace it:
+
+1. **Auto-follow.** A ResizeObserver on the content wrapper re-pins the scroller to the bottom while a sticky flag is armed. The flag disarms when the user scrolls up (detected as `scrollTop` decreasing while `scrollHeight` and `clientHeight` are stable, the same heuristic the built-in viewport uses, plus wheel-up and touchmove) and re-arms when the user returns to the bottom.
+2. **Measurement guard.** While pinned at the bottom, the virtualizer's own scroll adjustments on item re-measurement are suppressed via a custom `scrollToFn`; without this the two scroll writers fight and the view rubber-bands during streaming.
+3. **Run-start jump.** A `useLayoutEffect` observes `s.thread.isRunning` flipping to true and jumps to the bottom before paint, so a just-sent message never flashes below the fold. The `thread.runStart` event is deprecated; deriving the transition from state is the supported path.
+
+The production consumer this is extracted from disables streaming auto-follow entirely as a product choice; the example keeps following because it matches `ThreadPrimitive.Viewport`'s default behavior. Both are valid, and the disarm guard makes either safe.
+
+## Try it
+
+```sh
+npx assistant-ui@latest create my-app
+```
+
+Then copy `app/VirtualizedThread.tsx`, `app/MyRuntimeProvider.tsx`, and `app/seed-messages.ts` from [the example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-virtualized-thread), or clone the repo and run `pnpm --filter with-virtualized-thread dev`.

package/.docs/raw/docs/ink/adapters.mdx

@@ -1,6 +1,6 @@
 ---
 title: Adapters
-description: Title generation and storage adapters for React Ink.
+description: Attachment, title generation, and storage adapters for React Ink.
 ---
 
 Adapters customize runtime behavior. They can be passed as options to `useLocalRuntime` or `useRemoteThreadListRuntime`.
@@ -17,6 +17,28 @@ const adapter = createFileStorageAdapter({
 });
 ```
 
+## Attachment adapters
+
+`SimpleTextAttachmentAdapter` and `SimpleImageAttachmentAdapter` work the same in the terminal as on web and React Native. Text contents are sent to the model wrapped in `<attachment name=...>` tags, and images are sent as base64 data URLs.
+
+```ts
+import {
+  CompositeAttachmentAdapter,
+  SimpleImageAttachmentAdapter,
+  SimpleTextAttachmentAdapter,
+  useLocalRuntime,
+} from "@assistant-ui/react-ink";
+
+const runtime = useLocalRuntime(chatModelAdapter, {
+  adapters: {
+    attachments: new CompositeAttachmentAdapter([
+      new SimpleTextAttachmentAdapter(),
+      new SimpleImageAttachmentAdapter(),
+    ]),
+  },
+});
+```
+
 ## TitleGenerationAdapter
 
 Produces a thread title from a thread's messages. Pass one as the `titleGenerator` option to `createFileStorageAdapter`, or call it from a custom `RemoteThreadListAdapter`.

package/.docs/raw/docs/ink/hooks.mdx

@@ -62,7 +62,7 @@ useAuiEvent("thread.runStart", (payload) => {
 
 ### useNotification
 
-Ring the terminal bell and emit an OSC desktop notification when the assistant finishes a run, stops with an error, or pauses for human approval.
+Ring the terminal bell and emit an OSC desktop notification when the assistant finishes a run, stops with an error, or pauses for user input.
 
 ```tsx
 import { useNotification } from "@assistant-ui/react-ink";
@@ -130,7 +130,7 @@ const runtime = useLocalRuntime(chatModel, {
 | `adapters.feedback` | `FeedbackAdapter` | Adapter for message feedback (thumbs up/down) |
 | `adapters.suggestion` | `SuggestionAdapter` | Adapter for suggested prompts |
 | `cloud` | `AssistantCloud` | Cloud instance for thread persistence via `@assistant-ui/cloud` |
-| `unstable_humanToolNames` | `string[]` | Tool names that trigger a run interruption to wait for human/external approval |
+| `unstable_humanToolNames` | `string[]` | Tool names that pause the run until a result is added via `addResult` |
 
 ### useRemoteThreadListRuntime
 
@@ -155,37 +155,40 @@ const runtime = useRemoteThreadListRuntime({
 
 ### Tools
 
-Register tools with a toolkit. The tool definition is forwarded to the model, and when the model calls it, the `execute` function runs and the `render` component displays the result.
+Author tools with `defineToolkit`, the same API as on the web ([Defining Tools](/docs/tools/defining-tools)). The tool definition is forwarded to the model; when the model calls it, the `execute` function runs and the `render` component displays the result.
+
+<Callout type="info">
+  An Ink app runs in a single Node process, so there is no client/server
+  boundary to split and no build step. `defineToolkit` from
+  `@assistant-ui/react-ink` runs at runtime: import it as a value, with no
+  `"use generative"` directive and no `"use client"` inside `execute`.
+</Callout>
 
 ```tsx title="weather-toolkit.tsx"
-import type { Toolkit } from "@assistant-ui/react-ink";
+import { defineToolkit } from "@assistant-ui/react-ink";
 import { Text } from "ink";
+import { z } from "zod";
 
-export const toolkit = {
+export default defineToolkit({
   get_weather: {
-    type: "frontend",
     description: "Get the current weather for a city",
-    parameters: {
-      type: "object",
-      properties: {
-        city: { type: "string" },
-      },
-      required: ["city"],
-    },
+    parameters: z.object({ city: z.string() }),
     execute: async ({ city }) => {
       const res = await fetch(`https://api.weather.example/${city}`);
       return res.json();
     },
     render: ({ args, result }) => (
-      <Text>{args.city}: {result?.temperature}°F</Text>
+      <Text>
+        {args.city}: {result?.temperature}°F
+      </Text>
     ),
   },
-} satisfies Toolkit;
+});
 ```
 
 ```tsx title="ToolProvider.tsx"
 import { AuiProvider, Tools, useAui } from "@assistant-ui/react-ink";
-import { toolkit } from "./weather-toolkit";
+import toolkit from "./weather-toolkit";
 
 function ToolProvider({ children }: { children: React.ReactNode }) {
   const aui = useAui({ tools: Tools({ toolkit }) });
@@ -246,7 +249,7 @@ const WeatherCardUI = makeAssistantDataUI({
 Wrap a render function component so that it always uses the latest version without re-creating a stable reference. Useful when passing a render prop inline and the function closes over changing state.
 
 ```tsx title="weather-toolkit.tsx"
-import { type Toolkit, useInlineRender } from "@assistant-ui/react-ink";
+import { defineToolkit, useInlineRender } from "@assistant-ui/react-ink";
 import { Text } from "ink";
 import { useMemo } from "react";
 
@@ -257,12 +260,12 @@ export function useWeatherToolkit() {
 
   return useMemo(
     () =>
-      ({
+      defineToolkit({
         get_weather: {
           type: "backend",
           render,
         },
-      }) satisfies Toolkit,
+      }),
     [render],
   );
 }

package/.docs/raw/docs/migrations/toolkit-tools.mdx

@@ -103,25 +103,31 @@ export function App() {
 
 ## UI-Only Tool Renderers
 
-If you used `makeAssistantToolUI` or `useAssistantToolUI` for a backend, MCP, or LangGraph tool, the tool executes elsewhere, so there is no `execute` to author. That makes it a **render-only** entry, which belongs in a plain `satisfies Toolkit` object — not a `"use generative"` file (a generative tool must declare an `execute`). Author an explicit `type: "backend"` with just a `render`:
+If you used `makeAssistantToolUI` or `useAssistantToolUI` for a backend, MCP, or
+LangGraph tool, the tool executes elsewhere. Prefer a `"use generative"` toolkit
+with `execute: externalTool()` so the compiler omits the server entry, while the
+client keeps your renderer as `type: "backend"`:
 
 ```tsx
-// app/tool-ui.tsx
-"use client";
+// app/toolkit.tsx
+"use generative";
 
-import type { Toolkit } from "@assistant-ui/react";
+import { defineToolkit, externalTool } from "@assistant-ui/react";
 
-export const toolkit = {
+export default defineToolkit({
   web_search: {
-    type: "backend",
+    execute: externalTool(),
     render: ({ args, result }) => (
       <SearchResults query={args.query} results={result?.results ?? []} />
     ),
   },
-} satisfies Toolkit;
+});
 ```
 
-Register it like any toolkit: `useAui({ tools: Tools({ toolkit }) })`. Render-only entries upload no schema and run no browser code — they only attach UI for matching tool-call message parts.
+Register it like any toolkit: `useAui({ tools: Tools({ toolkit }) })`.
+Render-only entries upload no schema and run no browser code — they only attach
+UI for matching tool-call message parts. For MCP server catalogs, spread
+`defineMcpToolkit({ ... })` in the same generative toolkit.
 
 For a one-off renderer that should only affect a particular message surface, use `MessagePrimitive.Parts` inline tool render overrides instead of a global registration.
 

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

@@ -80,7 +80,7 @@ const runtime = useLocalRuntime(chatModel, {
 | `maxSteps` | `number` | Maximum tool call steps per run |
 | `cloud` | `AssistantCloud` | Optional cloud instance for persistence |
 | `adapters` | `object` | Optional adapter overrides (see below) |
-| `unstable_humanToolNames` | `string[]` | Tool names that pause the run for human approval |
+| `unstable_humanToolNames` | `string[]` | Tool names that pause the run until a result is added via `addResult` |
 
 The `adapters` option accepts the following fields (all optional):
 
@@ -116,39 +116,47 @@ const runtime = useRemoteThreadListRuntime({
 
 ### Tools
 
-Register tools with a toolkit. The tool definition is forwarded to the model, and when the model calls it, the `execute` function runs and the `render` component displays the result.
+Author tools in a `"use generative"` file with `defineToolkit`, the same API as on the web ([Defining Tools](/docs/tools/defining-tools)). The tool definition is forwarded to the model; when the model calls it, the `execute` function runs and the `render` component displays the result.
+
+Add the [`@assistant-ui/metro`](https://www.npmjs.com/package/@assistant-ui/metro) plugin so Metro compiles the `"use generative"` directive:
+
+```js title="metro.config.js"
+const { getDefaultConfig } = require("expo/metro-config");
+const { withAui } = require("@assistant-ui/metro");
+
+module.exports = withAui(getDefaultConfig(__dirname));
+```
 
 ```tsx title="weather-toolkit.tsx"
-import type { Toolkit } from "@assistant-ui/react-native";
+"use generative";
+
+import { defineToolkit } from "@assistant-ui/react-native";
 import { Text, View } from "react-native";
+import { z } from "zod";
 
-export const toolkit = {
+export default defineToolkit({
   get_weather: {
-    type: "frontend",
     description: "Get the current weather for a city",
-    parameters: {
-      type: "object",
-      properties: {
-        city: { type: "string" },
-      },
-      required: ["city"],
-    },
+    parameters: z.object({ city: z.string() }),
     execute: async ({ city }) => {
+      "use client";
       const res = await fetch(`https://api.weather.example/${city}`);
       return res.json();
     },
     render: ({ args, result }) => (
       <View>
-        <Text>{args.city}: {result?.temperature}°F</Text>
+        <Text>
+          {args.city}: {result?.temperature}°F
+        </Text>
       </View>
     ),
   },
-} satisfies Toolkit;
+});
 ```
 
 ```tsx title="ToolProvider.tsx"
 import { AuiProvider, Tools, useAui } from "@assistant-ui/react-native";
-import { toolkit } from "./weather-toolkit";
+import toolkit from "./weather-toolkit";
 
 function ToolProvider({ children }: { children: React.ReactNode }) {
   const aui = useAui({ tools: Tools({ toolkit }) });
@@ -188,7 +196,7 @@ useAssistantInstructions("You are a helpful weather assistant.");
 Wrap a tool UI component so that inline state updates (from a parent component's render) are reflected without remounting. Use this when the render function closes over props that change over time.
 
 ```tsx title="my-tool-toolkit.tsx"
-import { type Toolkit, useInlineRender } from "@assistant-ui/react-native";
+import { defineToolkit, useInlineRender } from "@assistant-ui/react-native";
 import { Text } from "react-native";
 import { useMemo } from "react";
 
@@ -199,12 +207,12 @@ export function useMyToolToolkit(someOuterProp: string) {
 
   return useMemo(
     () =>
-      ({
+      defineToolkit({
         my_tool: {
           type: "backend",
           render: stableRender,
         },
-      }) satisfies Toolkit,
+      }),
     [stableRender],
   );
 }

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

@@ -29,6 +29,45 @@ Reference for the runtime's API surface. Start with [quickstart](/docs/runtimes/
 | History | `adapters.history` | Per-thread message persistence. |
 | Thread list | `adapters.threadList` | Multi-thread switching (experimental, see below). |
 
+## Loading conversation history
+
+If your backend exposes the persisted AG-UI messages of a conversation (for
+example a `GET /agents/state` endpoint), use `fromAgUiMessages` to convert them
+to assistant-ui messages and return them from the history adapter so the thread
+is restored on page load:
+
+```tsx
+import { fromAgUiMessages } from "@assistant-ui/react-ag-ui";
+import { ExportedMessageRepository } from "@assistant-ui/react";
+
+const runtime = useAgUiRuntime({
+  agent,
+  adapters: {
+    history: {
+      async load() {
+        const { messages } = await fetch("/agents/state").then((r) => r.json());
+        return ExportedMessageRepository.fromArray(fromAgUiMessages(messages));
+      },
+      async append({ message }) {
+        // persist the newly sent message on your backend
+      },
+    },
+  },
+});
+```
+
+Messages sent during the session are always forwarded to the agent through the
+run input, independent of `append`. A no-op `append` is therefore only safe when
+your backend already persists the conversation on its own; otherwise those
+messages are gone on the next page load.
+
+`fromAgUiMessages` accepts an optional second argument: pass
+`{ showThinking: false }` to match a runtime configured with
+`showThinking: false`, so imported reasoning messages are dropped at conversion
+time, the same way a live run never stores them.
+
+`fromAgUiMessages` reconstructs the text, reasoning, and tool calls of each message. Multimodal user input (`image`, `audio`, `video`, and `document` parts, as well as legacy `binary` parts) is restored as attachments on the user message, so a backend that persists multimodal messages shows them again on reload and re-sends them on the next run. Legacy `binary` parts that only reference a file id are not restored.
+
 ## Thread list (experimental)
 
 <Callout type="warn">

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

@@ -353,15 +353,15 @@ Render the gate with a toolkit entry. The `approval` field carries the gate stat
 import { useChat } from "@ai-sdk/react";
 import {
   AssistantRuntimeProvider,
+  defineToolkit,
   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 = {
+const toolkit = defineToolkit({
   deploy: {
     type: "backend",
     render: ({ args, approval, respondToApproval, result }) => {
@@ -387,7 +387,7 @@ const toolkit = {
       return <p>Deployed {result.deployed}</p>;
     },
   },
-} satisfies Toolkit;
+});
 
 export default function Page() {
   const chat = useChat({

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

@@ -7,8 +7,8 @@ assistant-ui exposes runtime integrations at three layers. Understanding which l
 
 ## The three layers
 
-```mermaid
-graph TD
+<Flow.Root
+  llm={`graph TD
     subgraph Framework["Framework adapters"]
       A1[react-ai-sdk]
       A2[react-langgraph]
@@ -34,8 +34,50 @@ graph TD
     A6 --> C2
     A7 --> C2
     P1 --> C1
-    P2 --> C2
-```
+    P2 --> C2`}
+>
+  <Flow.Canvas
+    edges={[
+      { from: "datastream", to: "local", route: "down", midFrac: 0.4, laneOffset: -60 },
+      { from: "transport", to: "external", route: "down", midFrac: 0.65, toOffset: -14 },
+      { from: "adapters", to: "external", route: "down", midFrac: 0.4, toOffset: 14 },
+    ]}
+  >
+    <div className="grid max-w-2xl grid-cols-[1fr_1.6fr] gap-4">
+      <Flow.Group>
+        <Flow.GroupLabel>Protocol layers</Flow.GroupLabel>
+        <Flow.Column className="items-stretch gap-5">
+          <Flow.Row className="justify-start">
+            <Flow.Node flowId="datastream">DataStream</Flow.Node>
+          </Flow.Row>
+          <Flow.Row className="justify-end">
+            <Flow.Node flowId="transport">AssistantTransport</Flow.Node>
+          </Flow.Row>
+        </Flow.Column>
+      </Flow.Group>
+      <Flow.Group flowId="adapters">
+        <Flow.GroupLabel>Framework adapters</Flow.GroupLabel>
+        <Flow.Row className="flex-wrap justify-start">
+          <Flow.Node>react-ai-sdk</Flow.Node>
+          <Flow.Node>react-langgraph</Flow.Node>
+          <Flow.Node>react-langchain</Flow.Node>
+          <Flow.Node>react-google-adk</Flow.Node>
+          <Flow.Node>react-a2a</Flow.Node>
+          <Flow.Node>react-ag-ui</Flow.Node>
+          <Flow.Node>react-opencode</Flow.Node>
+        </Flow.Row>
+      </Flow.Group>
+    </div>
+    <div className="h-14" aria-hidden />
+    <Flow.Group className="mx-auto w-fit">
+      <Flow.GroupLabel>Core runtimes</Flow.GroupLabel>
+      <Flow.Row className="gap-10">
+        <Flow.Node flowId="local">LocalRuntime</Flow.Node>
+        <Flow.Node flowId="external">ExternalStoreRuntime</Flow.Node>
+      </Flow.Row>
+    </Flow.Group>
+  </Flow.Canvas>
+</Flow.Root>
 
 Each upper layer is implemented in terms of a lower one. You can drop down a layer whenever you need more control, but most users start at the framework layer and never touch the others.
 

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

@@ -30,7 +30,7 @@ A non-exhaustive list of `unstable_` exports surfaced in the runtime docs.
 | API | Package | Notes |
 | --- | --- | --- |
 | `unstable_createMessageConverter` | `@assistant-ui/react` | Message-format converter used by AssistantTransport and DataStream. |
-| `unstable_humanToolNames` | `@assistant-ui/react` | Tool names that pause for human approval. Only available on LocalRuntime; not supported in DataStream. |
+| `unstable_humanToolNames` | `@assistant-ui/react` | Tool names that pause the run until a result is added via `addResult`. Only available on LocalRuntime; not supported in DataStream. |
 | `unstable_threadListAdapter` | `@assistant-ui/react-langgraph` | LangGraph thread-list adapter slot on `useLangGraphRuntime`. |
 | `unstable_createLangGraphStream` | `@assistant-ui/react-langgraph` | End-to-end cancellation primitive. |
 | `unstable_Provider` | Various adapters | Thread-scoped provider on `RemoteThreadListAdapter`. Must render children synchronously. |

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

@@ -25,11 +25,17 @@ If you only need message streaming, [DataStream](/docs/runtimes/custom/data-stre
 
 ## Mental model
 
-```mermaid
-graph LR
+<Flow.Root
+  llm={`graph LR
     Frontend -->|Commands| Agent[Agent server]
-    Agent -->|State snapshots| Frontend
-```
+    Agent -->|State snapshots| Frontend`}
+>
+  <Flow.Row>
+    <Flow.Node>Frontend</Flow.Node>
+    <Flow.Arrow label="Commands" reverseLabel="State snapshots" length={150} />
+    <Flow.Node>Agent server</Flow.Node>
+  </Flow.Row>
+</Flow.Root>
 
 The frontend receives state snapshots and converts them to React components. The UI is a stateless view on top of the agent state.
 
@@ -37,21 +43,57 @@ The agent server receives commands from the frontend. When a user interacts with
 
 ### Command lifecycle
 
-```mermaid
-graph LR
+<Flow.Root
+  llm={`graph LR
     queued -->|sent to backend| in_transit
-    in_transit -->|backend processes| applied
-```
+    in_transit -->|backend processes| applied`}
+>
+  <Flow.Row>
+    <Flow.Node>queued</Flow.Node>
+    <Flow.Arrow label="sent to backend" length={120} />
+    <Flow.Node>in_transit</Flow.Node>
+    <Flow.Arrow label="backend processes" length={132} />
+    <Flow.Node>applied</Flow.Node>
+  </Flow.Row>
+</Flow.Root>
 
 The runtime alternates between **idle** (no active backend request) and **sending** (request in flight). When a new command is created while idle, it is sent immediately; otherwise it is queued until the current request completes.
 
-```mermaid
-graph LR
+<Flow.Root
+  llm={`graph LR
     idle -->|new command| sending
     sending -->|request completes| check{check queue}
     check -->|queue has commands| sending
-    check -->|queue empty| idle
-```
+    check -->|queue empty| idle`}
+>
+  <Flow.Canvas
+    edges={[
+      {
+        from: "check",
+        to: "sending",
+        route: "loop-bottom",
+        label: "queue has commands",
+        laneOffset: 28,
+      },
+      {
+        from: "check",
+        to: "idle",
+        route: "loop-bottom",
+        label: "queue empty",
+        laneOffset: 60,
+      },
+    ]}
+  >
+    <Flow.Row>
+      <Flow.Node flowId="idle">idle</Flow.Node>
+      <Flow.Arrow label="new command" length={108} />
+      <Flow.Node flowId="sending">sending</Flow.Node>
+      <Flow.Arrow label="request completes" length={132} />
+      <Flow.Node flowId="check" variant="decision">check queue</Flow.Node>
+    </Flow.Row>
+    <div className="h-20" aria-hidden />
+  </Flow.Canvas>
+</Flow.Root>
 
 To implement this you build two pieces:
 

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

@@ -206,7 +206,7 @@ const runtime = useDataStreamRuntime({
 ## Tool integration
 
 <Callout type="warn">
-Human-in-the-loop tools (`unstable_humanToolNames`, `human()` interrupts) are not supported in the data stream runtime. Use [`LocalRuntime`](/docs/runtimes/custom/local-runtime) directly if you need approval flows.
+Human-in-the-loop tools (`unstable_humanToolNames`, `human()` interrupts) are not supported in the data stream runtime. Use [`LocalRuntime`](/docs/runtimes/custom/local-runtime#human-in-the-loop-tools) directly if you need them.
 </Callout>
 
 ### Frontend tools