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

package/.docs/raw/docs/(reference)/api-reference/hooks/primitives.mdx

@@ -3,7 +3,7 @@ title: Primitive Hooks
 description: Primitive hooks for reading scoped assistant-ui runtime state, viewport behavior, timing, and message part data inside React components.
 ---
 
-import { useAssistantRuntime, useAttachmentRuntime, useCloudThreadListAdapter, useComposerRuntime, useEditComposerAttachmentRuntime, useMessageAttachmentRuntime, useMessagePartData, useMessagePartRuntime, useMessageRuntime, useScrollLock, useThreadComposerAttachmentRuntime, useThreadListItemRuntime, useThreadRuntime, useThreadViewportAutoScroll } from "@/generated/typeDocs";
+import { unstable_useMessageStallDetection, useAssistantRuntime, useAttachmentRuntime, useCloudThreadListAdapter, useComposerRuntime, useEditComposerAttachmentRuntime, useMessageAttachmentRuntime, useMessagePartData, useMessagePartRuntime, useMessageRuntime, useScrollLock, useThreadComposerAttachmentRuntime, useThreadListItemRuntime, useThreadRuntime, useThreadViewportAutoScroll } from "@/generated/typeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -637,4 +637,47 @@ const useThreadViewport: { (): ThreadViewportState; <TSelected>(selector: (state
 ```ts
 const useThreadViewportStore: { (): ReadonlyStore<ThreadViewportState>; (options: { optional: true; }): ReadonlyStore<ThreadViewportState> | null; };
 ```
+
+### unstable_useComposerInputHistory
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Under active development and might change without notice.
+</Callout>
+
+Terminal-style input history for the thread composer: ArrowUp on an
+empty draft recalls previously sent user messages (newest first),
+ArrowDown steps back toward the newest and finally restores the draft
+that was being typed when browsing started.
+
+Recall only triggers when the caret is on the first/last line with no
+selection, so multi-line editing keeps native arrow behavior. The
+handler yields to an open mention/slash popover, to IME composition,
+to modifier keys, and to consumer handlers that already called
+`preventDefault`. It is inert on edit composers.
+
+```tsx
+const history = unstable_useComposerInputHistory();
+<ComposerPrimitive.Input {...history} />
+```
+
+```ts
+function unstable_useComposerInputHistory(): Unstable_ComposerInputHistory;
+```
+
+### unstable_useMessageStallDetection
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Under active development and might change without notice.
+</Callout>
+
+Detects mid-run output stalls on the current message: while the message is
+running, watches a fingerprint of its content (part count plus text,
+argument, and result sizes) and reports a stall once the fingerprint stops
+changing for `thresholdMs`. Useful for re-surfacing a "still working"
+indicator during tool think-time or provider stalls, after the first
+tokens have already streamed.
+
+Must be used inside a message scope.
+
+<ParametersTable {...unstable_useMessageStallDetection} />
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/model-context/context.mdx

@@ -29,7 +29,7 @@ const mergeModelContexts: (configSet: Set<ModelContextProvider>) => ModelContext
 ### ModelContextClient
 
 ```ts
-const ModelContextClient: () => ResourceElement<ClientOutput<"modelContext">, undefined>;
+const ModelContextClient: Resource<ClientOutput<"modelContext">, []>;
 ```
 
 ### ModelContextProvider

package/.docs/raw/docs/(reference)/api-reference/tools/rendering.mdx

@@ -3,7 +3,7 @@ title: Tool Rendering
 description: Register React renderers for assistant-ui tool calls, tool results, and model data parts.
 ---
 
-import { McpAppRenderer, McpAppsRemoteHost, getMcpAppFromToolPart, useAssistantDataUI, useAssistantToolUI } from "@/generated/typeDocs";
+import { DataRenderers, McpAppRenderer, McpAppsRemoteHost, getMcpAppFromToolPart, useAssistantDataUI, useAssistantToolUI } from "@/generated/typeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -16,15 +16,7 @@ import { McpAppRenderer, McpAppsRemoteHost, getMcpAppFromToolPart, useAssistantD
 
 ### DataRenderers
 
-Registers renderers for `data` message parts.
-
-Data renderers are looked up by the part's `name` field. Use this resource
-directly for a renderer scope, or prefer [useAssistantDataUI](/docs/api-reference/tools/rendering#useassistantdataui) /
-[makeAssistantDataUI](/docs/api-reference/tools/rendering#makeassistantdataui) when registering from React components.
-
-```ts
-const DataRenderers: () => ResourceElement<ClientOutput<"dataRenderers">, undefined>;
-```
+<ParametersTable {...DataRenderers} />
 
 ### getMcpAppFromToolPart
 
@@ -84,23 +76,10 @@ const makeAssistantToolUI: <TArgs, TResult>(tool: AssistantToolUIProps<TArgs, TR
 
 ### McpAppRenderer
 
-Creates a tool-call renderer for MCP Apps embedded in assistant messages.
-
-Compose this into the `Tools` resource through its `mcpApp` option. When a
-tool-call part carries `mcp.app` metadata for a `ui://` resource, the
-renderer loads that resource from the configured host and displays it in a
-sandboxed frame.
-
 <ParametersTable {...McpAppRenderer} />
 
 ### McpAppsRemoteHost
 
-Creates the default HTTP host for MCP App widgets.
-
-The host POSTs widget requests to the configured route as `{ method,
-params }`, using the method names expected by the assistant-ui MCP Apps
-guide.
-
 <ParametersTable {...McpAppsRemoteHost} />
 
 ### useAssistantDataUI

package/.docs/raw/docs/(reference)/api-reference/tools/status.mdx

@@ -39,4 +39,26 @@ function WeatherToolUI({
 ```ts
 const useToolArgsStatus: <TArgs extends Record<string, unknown> = Record<string, unknown>>() => ToolArgsStatus<TArgs>;
 ```
+
+### useToolCallElapsed
+
+Hook that returns the elapsed wall-clock time of the current tool call in
+milliseconds, ticking once per second while the call runs.
+
+Reads `part.timing`. Returns `undefined` when the part is not a tool call,
+carries no timing, ended without a recorded completion (the duration is
+unknown), or when no message part scope is available (so kit components
+stay renderable standalone, e.g. in docs previews).
+
+```tsx
+function ToolDuration() {
+  const elapsedMs = useToolCallElapsed();
+  if (elapsedMs === undefined) return null;
+  return <span>{(elapsedMs / 1000).toFixed(1)}s</span>;
+}
+```
+
+```ts
+const useToolCallElapsed: () => number;
+```
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/tools/toolkits.mdx

@@ -80,13 +80,6 @@ type Toolkit = Record<string, ToolDefinition<any, any>>;
 
 ### Tools
 
-Registers tools with model context and installs tool-call renderers.
-
-Mount this resource near an assistant subtree when you want to expose a
-group of tools declaratively. Tool definitions are registered with model
-context, while each tool renderer is registered with the tools scope for
-message rendering.
-
 <ParametersTable {...Tools} />
 
 ### defineMcpToolkit

package/.docs/raw/docs/(reference)/api-reference/utilities/miscellaneous.mdx

@@ -3,7 +3,7 @@ title: Utilities
 description: Miscellaneous @assistant-ui/react utilities for custom rendering, composition, and advanced assistant UI behavior.
 ---
 
-import { AssistantCloud, ChainOfThoughtClient, DevToolsHooks, InMemoryThreadList, SingleThreadList } from "@/generated/typeDocs";
+import { AssistantCloud, ChainOfThoughtClient, DevToolsHooks, InMemoryThreadList, Interactables, SingleThreadList, Suggestions, useSmooth } from "@/generated/typeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -38,35 +38,34 @@ const createMessageQueue: (driver: MessageQueueDriver) => MessageQueueController
 
 ### Interactables
 
-```ts
-const Interactables: () => ResourceElement<ClientOutput<"interactables">, undefined>;
-```
+<ParametersTable {...Interactables} />
 
 ### SingleThreadList
 
-A minimal threads scope that wraps a single thread.
-Automatically provided by ExternalThread when no threads scope exists.
-Mounts the provided thread resource element.
-
 <ParametersTable {...SingleThreadList} />
 
 ### Suggestions
 
-```ts
-const Suggestions: {
-  (): ResourceElement<
-    ClientOutput<"suggestions">,
-    undefined
-  >;
-  (
-    suggestions: SuggestionConfig[],
-  ): ResourceElement<
-    ClientOutput<"suggestions">,
-    SuggestionConfig[]
-  >;
-};
+<ParametersTable {...Suggestions} />
+
+### useSmooth
+
+Animates streamed message part text with a typewriter-style reveal.
+
+Takes the current part state and a `smooth` argument: `false` disables,
+`true` uses the default rate, and a SmoothOptions object tunes
+the reveal. Returns the part state with `text` replaced by the revealed
+prefix and `status` reporting `running` until the reveal catches up.
+
+```tsx
+const { text, status } = useSmooth(useMessagePartText(), {
+  drainMs: 500,
+  maxCharsPerFrame: 30,
+});
 ```
 
+<ParametersTable {...useSmooth} />
+
 ### unstable_defaultDirectiveFormatter
 
 Default directive formatter using the `:type[label]{name=id}` syntax.

package/.docs/raw/docs/guides/chain-of-thought.mdx

@@ -60,7 +60,7 @@ const AssistantMessage: FC = () => {
             case "group-reasoning": {
               const running = part.status.type === "running";
               return (
-                <ReasoningRoot defaultOpen={running}>
+                <ReasoningRoot streaming={running}>
                   <ReasoningTrigger active={running} />
                   <ReasoningContent aria-busy={running}>
                     <ReasoningText>{children}</ReasoningText>

package/.docs/raw/docs/guides/index.mdx

@@ -68,6 +68,9 @@ Render specialized message content.
   <Card title="LaTeX" href="/docs/guides/latex">
     Render math via React Markdown or Streamdown, with streaming-safe escape rules.
   </Card>
+  <Card title="Thread Virtualization" href="/docs/guides/virtualization">
+    Render very long threads with @tanstack/react-virtual and per-index message rendering.
+  </Card>
 </Cards>
 
 ## Audio

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/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
 

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):
 

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

@@ -66,9 +66,7 @@ messages are gone on the next page load.
 `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. Non-text message content such as images and files is not restored, so a
-backend that persists multimodal messages loads only their text on reload.
+`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)
 

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/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

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.
@@ -743,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/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