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

package/.docs/raw/docs/tools/tool-ui.mdx

@@ -577,12 +577,48 @@ const toolkit = defineToolkit({
 
 - `undefined`: gate is open, the renderer should ask the user. This is the only state in which `respondToApproval` is legal.
 - `true`: decision recorded as allow. The server is producing the result (or has produced one, available on `result`).
-- `false`: decision recorded as deny. `output-denied` from the runtime sets `isError` and exposes `approval.reason`.
+- `false`: decision recorded as deny. The runtime records an error result (`isError`) and exposes `approval.reason`.
 
 `approval.isAutomatic` is `true` when the runtime granted the decision from a server-side policy rather than the user; render a "auto-approved" badge instead of buttons in that case.
 
+Approval gates require a runtime that implements them: the AI SDK v6 runtime emits them for `needsApproval` tools, and `LocalRuntime` supports gates emitted by your `ChatModelAdapter`; see [LocalRuntime approval gates](/docs/runtimes/custom/local-runtime#approval-gates). For tools where the user supplies the result itself, use `unstable_humanToolNames` with `addResult` instead; see [human-in-the-loop tools](/docs/runtimes/custom/local-runtime#human-in-the-loop-tools).
+
 For the wire-side setup (`needsApproval`, `sendAutomaticallyWhen`), see [AI SDK v6 server-side tool approval](/docs/runtimes/ai-sdk/v6#server-side-tool-approval).
 
+### Approval options
+
+Beyond the plain allow / deny pair, the host can attach a list of decision options to an approval, for example "allow once", "allow for this session", and "always allow". Each option carries a machine-readable `kind` (`"allow-once"`, `"allow-always"`, `"reject-once"`, `"reject-always"`); scope semantics like session versus global belong to the option's `id` and `label`, which only the host interprets:
+
+```ts
+const approval = {
+  id: "a1",
+  options: [
+    { id: "once", kind: "allow-once" },
+    { id: "session", kind: "allow-always", label: "Allow for this session" },
+    {
+      id: "always",
+      kind: "allow-always",
+      label: "Always allow",
+      grants: ["git *"],
+      confirm: true,
+    },
+    { id: "deny", kind: "reject-once" },
+  ],
+};
+```
+
+Renderers respond with the chosen option instead of a boolean; the option's kind resolves the decision:
+
+```tsx
+respondToApproval({ optionId: "session" });
+```
+
+The runtime receives `{ approvalId, approved, optionId, reason? }`, so a host that persists "always allow" decisions can key its store off `optionId`. Persistence is entirely host-owned: assistant-ui never stores a decision and never auto-answers future approvals. `grants` lists the patterns an option would persist (shown to the user before they commit), and `confirm` opts the option into a confirmation step. Options with custom `_`-prefixed kinds are skipped by the default `ToolFallback` bar and must be answered with an explicit `approved` value, optionally alongside the `optionId` so the chosen option is still recorded.
+
+Approvals that end without a decision (a cancelled run or an expired request) are recorded by the host as `approval.resolution: "cancelled" | "expired"`, which closes the gate without recording a deny.
+
+The default `ToolFallback` component renders supplied options automatically, including the confirmation step.
+
 ## Advanced Features
 
 ### Tool Status Handling

package/.docs/raw/docs/ui/dot-matrix.mdx

@@ -0,0 +1,133 @@
+---
+title: Dot Matrix
+description: Tiny 5x5 dot-matrix indicator with 20 state-specific blink patterns.
+platforms: ["react"]
+---
+
+import { PreviewCode } from "@/components/docs/preview-code.server";
+import {
+  DotMatrixSample,
+  DotMatrixLifecycleSample,
+  DotMatrixInlineSample,
+  DotMatrixSizesSample,
+} from "@/components/docs/samples/dot-matrix";
+
+<Callout>
+  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
+</Callout>
+
+<DotMatrixSample />
+
+## Installation
+
+<InstallCommand shadcn={["dot-matrix"]} />
+
+This adds a `/components/assistant-ui/dot-matrix.tsx` file to your project, which you can adjust as needed. The component has no dependencies beyond React.
+
+## Usage
+
+```tsx
+import { DotMatrix } from "@/components/assistant-ui/dot-matrix";
+
+export function RunIndicator({ isRunning }: { isRunning: boolean }) {
+  return <DotMatrix state={isRunning ? "loading" : "success"} />;
+}
+```
+
+Dots inherit the surrounding text color, so the matrix renders dark dots on light backgrounds and light dots on dark backgrounds without configuration. Every state is a combination of a dot pattern, a motion, and a color, and switching states cross-fades each dot into its new pattern.
+
+## States
+
+| State | Pattern |
+|-------|---------|
+| `idle` | Dim static grid |
+| `loading` | Randomized twinkle (default) |
+| `thinking` | Diagonal wave |
+| `streaming` | Falling rain, per-column streaks |
+| `searching` | Horizontal sweep |
+| `syncing` | Rotating sweep around the center |
+| `connecting` | Ripple expanding from the center |
+| `waiting` | Ellipsis dots blinking in sequence |
+| `uploading` | Wave rising upward |
+| `downloading` | Wave falling downward |
+| `listening` | Slow equalizer columns |
+| `speaking` | Fast equalizer columns |
+| `recording` | Red center dot breathing |
+| `success` | Green check glyph, static |
+| `error` | Red cross glyph, blinking |
+| `warning` | Amber exclamation glyph, slow blink |
+| `info` | Blue info glyph, static |
+| `paused` | Pause bars glyph, static |
+| `stopped` | Square glyph, static |
+| `offline` | Very dim static grid |
+
+The component exports `dotMatrixStates` (the ordered list above) and the `DotMatrixState` union type, so UIs can enumerate or map states without duplicating the list. New states are added by extending the `STATES` record in the component source with a glyph and a per-dot blink function.
+
+## Examples
+
+### State Lifecycle
+
+Drive the `state` prop from your run status; the matrix morphs between patterns instead of swapping components.
+
+<PreviewCode file="components/docs/samples/dot-matrix" name="DotMatrixLifecycleSample">
+  <DotMatrixLifecycleSample />
+</PreviewCode>
+
+### Inline With Text
+
+At the default `size-4` the matrix aligns with text like an icon, and the dots adapt to inverted surfaces through `currentColor`.
+
+<PreviewCode file="components/docs/samples/dot-matrix" name="DotMatrixInlineSample">
+  <DotMatrixInlineSample />
+</PreviewCode>
+
+### Sizes
+
+The matrix is an SVG, so any size utility scales it crisply.
+
+<DotMatrixSizesSample />
+
+## How It Works
+
+The grid is a 5x5 SVG of `currentColor` circles. Blinking is a single CSS keyframe animation whose high/low opacity bounds come from registered per-dot CSS variables; the animation runs in every state (static states collapse the bounds) and the bounds carry a transition, which is what makes state changes cross-fade per dot. The randomized loading rhythm uses deterministic per-dot delays and durations, so server and client render identical markup and no JavaScript runs after render. With `prefers-reduced-motion`, the dots hold their resting opacity instead of blinking.
+
+The root is a `role="status"` live region whose text content is the state name (or the `label` prop), so screen readers announce state changes; the SVG itself is `aria-hidden`.
+
+## API Reference
+
+### DotMatrix
+
+<ParametersTable
+  type="DotMatrixProps"
+  parameters={[
+    {
+      name: "state",
+      type: "DotMatrixState",
+      default: '"loading"',
+      description:
+        "One of the 20 built-in states listed above, controlling pattern, motion, and color.",
+    },
+    {
+      name: "label",
+      type: "string",
+      description:
+        "Accessible label announced by screen readers. Defaults to the state name.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description:
+        "Additional CSS classes. Use size utilities to scale and text color utilities to recolor.",
+    },
+  ]}
+/>
+
+### Styling
+
+Color follows `currentColor`, so `className="text-blue-500"` recolors the whole matrix; the outcome states (`success`, `error`, `warning`, `info`, `recording`, and the muted static states) set their own color which a `className` can override. Dots are targetable via `[data-slot="dot-matrix"]` and `[data-slot="dot-matrix-dot"]`, and the current state is exposed as `data-state` on the root.
+
+## Related Components
+
+- [Number Roll](/docs/ui/number-roll) - Animated rolling number
+- [Badge](/docs/ui/badge) - Small status and metadata labels
+- [Voice](/docs/ui/voice) - Voice activity visualization

package/.docs/raw/docs/ui/model-selector.mdx

@@ -1,12 +1,12 @@
 ---
-title: ModelSelector
-description: Model picker with unified overlay positioning and runtime integration.
+title: Model Selector
+description: Composable model picker with reasoning effort levels, search, and runtime integration.
 platforms: ["react"]
 ---
 
 import { ModelSelectorSample } from "@/components/docs/samples/model-selector";
 
-A select component that lets users switch between AI models. Uses item-aligned positioning so the selected model overlays the trigger for a unified look. Integrates with assistant-ui's `ModelContext` system to automatically propagate the selected model to your backend.
+A picker that lets users switch between AI models and choose a reasoning effort (thinking) level. It is built on Popover + Command, so search, provider grouping, and filtering compose in without being built in. The default export integrates with assistant-ui's `ModelContext` system, so the selection reaches your backend on every request with no extra wiring.
 
 <ModelSelectorSample />
 
@@ -24,9 +24,9 @@ A select component that lets users switch between AI models. Uses item-aligned p
 
 ### Use in your application
 
-Place the `ModelSelector` inside your thread component, typically in the composer area:
+Place the `ModelSelector` inside your thread component, typically in the composer area. Each model needs an `id` and a display `name`; everything else is optional:
 
-```tsx title="/components/assistant-ui/thread.tsx" {1,6-14}
+```tsx title="/components/assistant-ui/thread.tsx" {1,6-15}
 import { ModelSelector } from "@/components/assistant-ui/model-selector";
 
 const ComposerAction: FC = () => {
@@ -36,9 +36,10 @@ const ComposerAction: FC = () => {
         models={[
           { id: "gpt-5.4-nano", name: "GPT-5.4 Nano", description: "Fast and efficient" },
           { id: "gpt-5.4-mini", name: "GPT-5.4 Mini", description: "Balanced performance" },
-          { id: "gpt-5.5", name: "GPT-5.5", description: "Most capable" },
+          { id: "gpt-5.5", name: "GPT-5.5", description: "Most capable", efforts: true },
         ]}
         defaultValue="gpt-5.4-nano"
+        defaultEffort="medium"
         size="sm"
       />
     </div>
@@ -49,16 +50,22 @@ const ComposerAction: FC = () => {
   </Step>
   <Step>
 
-### Read the model in your API route
+### Read the selection in your API route
 
-The selected model's `id` is sent as `config.modelName` in the request body:
+The selected model's `id` arrives as `config.modelName`, and the effort level as `config.reasoningEffort`:
 
-```tsx title="app/api/chat/route.ts" {2,5}
+```tsx title="app/api/chat/route.ts" {2,5-11}
 export async function POST(req: Request) {
   const { messages, config } = await req.json();
 
   const result = streamText({
     model: openai(config?.modelName ?? "gpt-5.4-nano"),
+    providerOptions: {
+      openai:
+        config?.reasoningEffort !== undefined
+          ? { reasoningEffort: config.reasoningEffort }
+          : {},
+    },
     messages: await convertToModelMessages(messages),
   });
 
@@ -66,77 +73,126 @@ export async function POST(req: Request) {
 }
 ```
 
+`config.reasoningEffort` is only present when the selected model supports the chosen level, so the route only forwards it when it exists. See [How It Works](#how-it-works).
+
   </Step>
 </Steps>
 
-## Variants
+## Reasoning Efforts
 
-Use the `variant` prop to change the trigger's visual style.
+A model that declares `efforts` shows a "Thinking" row at the bottom of the popover. `efforts: true` enables the default Low / Medium / High levels; pass a list of `{ id, name }` objects to define your own:
 
 ```tsx
-<ModelSelector variant="outline" /> // Border (default)
-<ModelSelector variant="ghost" />   // No background
-<ModelSelector variant="muted" />   // Solid background
+{
+  id: "gpt-5.5",
+  name: "GPT-5.5",
+  efforts: [
+    { id: "minimal", name: "Minimal" },
+    { id: "high", name: "High" },
+  ],
+}
 ```
 
-| Variant   | Description                                    |
-| --------- | ---------------------------------------------- |
-| `outline` | Border with transparent background (default)   |
-| `ghost`   | No background, subtle hover                    |
-| `muted`   | Solid secondary background                     |
+Omit `efforts` for models without configurable reasoning. The row is hidden while such a model is selected.
 
-## Sizes
+### Sticky Selection
 
-Use the `size` prop to control the trigger dimensions.
+The effort selection survives model switches. Switching to a model that doesn't support the current level omits `reasoningEffort` from the request instead of resetting the user's choice, and the level applies again when the user switches back. The exported `resolveModelEffort` helper applies the same rule if you build your own runtime integration around `ModelSelector.Root`; see [`resolveModelEffort`](#resolvemodeleffort).
 
-```tsx
-<ModelSelector size="sm" />      // Compact (h-8, text-xs)
-<ModelSelector size="default" /> // Standard (h-9)
-<ModelSelector size="lg" />      // Large (h-10)
-```
-
-## Model Options
+### Custom Effort UI
 
-Each model in the `models` array supports:
+`ModelSelector.Effort` lays the levels out as horizontal segments, which overflows the popover width once a model has more than a few. For those cases, or for a different layout such as a slider or a sub-dropdown, build your own control with the `useModelSelectorEfforts` hook. It exposes the selected model's levels and the active selection:
 
 ```tsx
-const models = [
-  {
-    id: "gpt-5.4-nano",           // Sent to backend as config.modelName
-    name: "GPT-5.4 Nano",   // Display name in trigger and items
-    description: "Fast and efficient", // Optional subtitle in items only
-    icon: <SparklesIcon />,      // Optional icon (any ReactNode)
-  },
-];
+import { useModelSelectorEfforts } from "@/components/assistant-ui/model-selector";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+
+function EffortDropdown() {
+  const { efforts, effort, setEffort } = useModelSelectorEfforts();
+  if (!efforts?.length) return null;
+
+  return (
+    <div className="flex items-center justify-between gap-3 border-t px-3 py-2">
+      <span className="text-muted-foreground text-xs">Thinking</span>
+      <DropdownMenu>
+        <DropdownMenuTrigger className="text-xs">
+          {efforts.find((e) => e.id === effort)?.name ?? "Select"}
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuRadioGroup value={effort} onValueChange={setEffort}>
+            {efforts.map((option) => (
+              <DropdownMenuRadioItem key={option.id} value={option.id}>
+                {option.name}
+              </DropdownMenuRadioItem>
+            ))}
+          </DropdownMenuRadioGroup>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+}
 ```
 
-## Runtime Integration
+Render it inside `ModelSelector.Content` in place of `ModelSelector.Effort`. The same hook supports any shape that reads the levels and writes the selection.
 
-The default `ModelSelector` export automatically registers the selected model with assistant-ui's `ModelContext` system. When a user selects a model:
+## Search
 
-1. The component calls `aui.modelContext().register()` with `config.modelName`
-2. The `AssistantChatTransport` includes `config` in the request body
-3. Your API route reads `config.modelName` to determine which model to use
+Search is opt-in. Pass `searchable` to the default component:
 
-This works out of the box with `@assistant-ui/react-ai-sdk`.
+```tsx
+<ModelSelector models={models} searchable />
+```
 
-## API Reference
+Or compose `ModelSelector.Search` into a custom layout. Matching runs against each model's `id`, `name`, and `keywords`; add the provider name to `keywords` so typing "openai" finds its models.
 
-### Composable API
+## Composition
 
-For custom layouts, use the sub-components directly with `ModelSelector.Root`:
+All parts are exported individually. The default popover content is `List` + `Effort`; replace it to add search, provider groups, or anything else:
 
 ```tsx
 import {
   ModelSelectorRoot,
   ModelSelectorTrigger,
   ModelSelectorContent,
+  ModelSelectorSearch,
+  ModelSelectorList,
+  ModelSelectorEmpty,
+  ModelSelectorGroup,
   ModelSelectorItem,
+  ModelSelectorEffort,
 } from "@/components/assistant-ui/model-selector";
 
-<ModelSelectorRoot models={models} value={modelId} onValueChange={setModelId}>
+<ModelSelectorRoot
+  models={models}
+  value={modelId}
+  onValueChange={setModelId}
+  effort={effort}
+  onEffortChange={setEffort}
+>
   <ModelSelectorTrigger variant="outline" />
-  <ModelSelectorContent />
+  <ModelSelectorContent>
+    <ModelSelectorSearch placeholder="Search models..." />
+    <ModelSelectorList>
+      <ModelSelectorEmpty />
+      <ModelSelectorGroup heading="OpenAI">
+        {openaiModels.map((model) => (
+          <ModelSelectorItem key={model.id} model={model} />
+        ))}
+      </ModelSelectorGroup>
+      <ModelSelectorGroup heading="Anthropic">
+        {anthropicModels.map((model) => (
+          <ModelSelectorItem key={model.id} model={model} />
+        ))}
+      </ModelSelectorGroup>
+    </ModelSelectorList>
+    <ModelSelectorEffort label="Thinking" />
+  </ModelSelectorContent>
 </ModelSelectorRoot>
 ```
 
@@ -144,9 +200,64 @@ import {
 |-----------|-------------|
 | `ModelSelector` | Default export with runtime integration |
 | `ModelSelector.Root` | Presentational root (no runtime, controlled state) |
-| `ModelSelector.Trigger` | CVA-styled trigger showing current model |
-| `ModelSelector.Content` | Select content with model items |
-| `ModelSelector.Item` | Individual model option with icon, name, description |
+| `ModelSelector.Trigger` | CVA-styled trigger showing the current selection |
+| `ModelSelector.Value` | Selected model name, icon, and active effort |
+| `ModelSelector.Content` | Popover content wrapping a Command |
+| `ModelSelector.Search` | Search input that filters the list |
+| `ModelSelector.List` | List of model items (renders all models by default) |
+| `ModelSelector.Empty` | Empty state shown when search has no matches |
+| `ModelSelector.Group` | Labeled group of items (e.g. by provider) |
+| `ModelSelector.Separator` | Divider between groups or items |
+| `ModelSelector.Item` | Individual model option |
+| `ModelSelector.Effort` | Thinking level row for the selected model |
+
+`ModelSelector.List` is a Command list, so filtering and keyboard navigation work across groups automatically. Custom sorting is plain code: order the models before rendering items.
+
+<Callout type="warn">
+  `ModelSelector.Content` wraps a Command whose root keydown handler claims
+  <kbd>Enter</kbd> to select the highlighted model. Interactive elements
+  composed inside it (filter chips, custom effort controls) should stop
+  propagation for Enter in their own `onKeyDown` so the focused control
+  activates instead. `ModelSelector.Effort` already does this.
+</Callout>
+
+## Variants
+
+Use the `variant` prop to change the trigger's visual style.
+
+```tsx
+<ModelSelector variant="outline" /> // Border (default)
+<ModelSelector variant="ghost" />   // No background
+<ModelSelector variant="muted" />   // Solid background
+```
+
+| Variant   | Description                                    |
+| --------- | ---------------------------------------------- |
+| `outline` | Border with transparent background (default)   |
+| `ghost`   | No background, subtle hover                    |
+| `muted`   | Solid secondary background                     |
+
+## Sizes
+
+Use the `size` prop to control the trigger dimensions.
+
+```tsx
+<ModelSelector size="sm" />      // Compact (h-8, text-xs)
+<ModelSelector size="default" /> // Standard (h-9)
+<ModelSelector size="lg" />      // Large (h-10)
+```
+
+## How It Works
+
+The default `ModelSelector` export registers the selection with assistant-ui's `ModelContext` system:
+
+1. The component calls `aui.modelContext().register()` with `config.modelName`, plus `config.reasoningEffort` when the selected model supports the chosen level
+2. The `AssistantChatTransport` includes `config` in the request body of every chat request
+3. Your API route reads `config.modelName` and `config.reasoningEffort`
+
+This works out of the box with `@assistant-ui/react-ai-sdk`. `ModelSelector.Root` performs no registration; it is purely presentational, with controlled and uncontrolled props for the value, effort, and open state.
+
+## API Reference
 
 ### ModelSelector
 
@@ -162,7 +273,7 @@ import {
     {
       name: "defaultValue",
       type: "string",
-      description: "Initial model ID for uncontrolled usage.",
+      description: "Initial model ID for uncontrolled usage. Defaults to the first model, captured on first render; if models loads asynchronously, control the value instead.",
     },
     {
       name: "value",
@@ -174,6 +285,27 @@ import {
       type: "(value: string) => void",
       description: "Callback when selected model changes.",
     },
+    {
+      name: "defaultEffort",
+      type: "string",
+      description: "Initial effort level ID for uncontrolled usage.",
+    },
+    {
+      name: "effort",
+      type: "string",
+      description: "Controlled effort level ID.",
+    },
+    {
+      name: "onEffortChange",
+      type: "(effort: string) => void",
+      description: "Callback when effort level changes.",
+    },
+    {
+      name: "searchable",
+      type: "boolean",
+      default: "false",
+      description: "Render a search input above the model list.",
+    },
     {
       name: "variant",
       type: '"outline" | "ghost" | "muted"',
@@ -221,5 +353,40 @@ import {
       type: "React.ReactNode",
       description: "Optional icon displayed before the model name.",
     },
+    {
+      name: "disabled",
+      type: "boolean",
+      description: "Disable selection of this model.",
+    },
+    {
+      name: "keywords",
+      type: "string[]",
+      description: "Extra search terms matched by ModelSelector.Search (e.g. the provider name).",
+    },
+    {
+      name: "efforts",
+      type: "boolean | ModelSelectorEffortOption[]",
+      description: "Reasoning effort levels. true enables the default Low/Medium/High; pass a custom { id, name } list to override. Omit for models without configurable reasoning.",
+    },
   ]}
 />
+
+### `useModelSelectorEfforts`
+
+```tsx
+const { efforts, effort, setEffort } = useModelSelectorEfforts();
+```
+
+The selected model's effort levels and the active selection, for building a [custom effort UI](#custom-effort-ui) inside `ModelSelector.Content`. `efforts` is `undefined` for models without configurable reasoning.
+
+### `resolveModelEffort`
+
+```tsx
+resolveModelEffort(models, modelId, effort); // => string | undefined
+```
+
+Returns the effort ID when the given model supports it, otherwise `undefined`. This is the [sticky selection](#sticky-selection) rule the default component applies before registering the selection.
+
+## Related
+
+- [Model Context](/docs/copilots/model-context): How registered context (instructions, tools, config) reaches your backend