@assistant-ui/mcp-docs-server 0.1.25 → 0.1.26

package/.docs/raw/docs/(docs)/guides/interactables.mdx

@@ -0,0 +1,292 @@
+---
+title: Interactables
+description: Persistent UI whose state can be read and updated by the AI assistant.
+---
+
+import { InteractableSample } from "@/components/docs/samples/interactable";
+
+Interactables are React components that live outside the chat message flow and have state that both the user and the AI can read and write. This enables AI-driven UI patterns where the assistant controls parts of your application beyond the chat window.
+
+<InteractableSample />
+
+## Overview
+
+Unlike regular tool UIs that appear inline within messages, interactables:
+
+- **Persist across messages** — they live outside the chat thread
+- **Have shared state** — both the user (via React) and the AI (via auto-generated tools) can update them
+- **Support partial updates** — the AI only needs to send the fields it wants to change
+- **Are developer-placed** — you decide where they render in your app
+- **Auto-register tools** — the AI automatically gets a tool to update each interactable's state
+
+Common use cases:
+
+- Task boards that the AI can add items to
+- Data dashboards that update based on conversation
+- Forms that the AI pre-fills
+- Canvas/editor components that the AI can manipulate
+
+## Quick Start
+
+### 1. Register the Interactables scope
+
+```tsx
+import { useAui, Interactables, AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
+  const runtime = useChatRuntime();
+
+  const aui = useAui({
+    interactables: Interactables(),
+  });
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+### 2. Create an interactable
+
+<Callout type="warn">
+  Define the `stateSchema` and `initialState` **outside** the component (or
+  memoize them). Creating a new schema on every render will cause the
+  interactable to re-register and reset its state.
+</Callout>
+
+```tsx
+import { useInteractable } from "@assistant-ui/react";
+import { z } from "zod";
+
+const taskBoardSchema = z.object({
+  tasks: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      done: z.boolean(),
+    }),
+  ),
+});
+
+const taskBoardInitialState = { tasks: [] };
+
+function TaskBoard() {
+  const [state, setState] = useInteractable("taskBoard", {
+    description: "A task board showing the user's tasks",
+    stateSchema: taskBoardSchema,
+    initialState: taskBoardInitialState,
+  });
+
+  return (
+    <div>
+      <h2>Tasks</h2>
+      <ul>
+        {state.tasks.map((task) => (
+          <li key={task.id}>
+            <label>
+              <input
+                type="checkbox"
+                checked={task.done}
+                onChange={() =>
+                  setState((prev) => ({
+                    tasks: prev.tasks.map((t) =>
+                      t.id === task.id ? { ...t, done: !t.done } : t,
+                    ),
+                  }))
+                }
+              />
+              {task.title}
+            </label>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### 3. Place it in your layout
+
+```tsx
+function App() {
+  return (
+    <MyRuntimeProvider>
+      <div className="flex">
+        <Thread className="flex-1" />
+        <TaskBoard /> {/* Lives outside the chat */}
+      </div>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+Now when the user says _"Add a task called 'Buy groceries'"_, the AI will automatically call the `update_taskBoard` tool to update the state. Thanks to partial updates, the AI only needs to send the fields it wants to change.
+
+## Partial Updates
+
+Auto-generated tools use a partial schema — all fields become optional. The AI only sends the fields it wants to change; omitted fields keep their current values.
+
+```tsx
+// If the state is { title: "My Note", content: "Hello", color: "yellow" }
+// The AI can call: update_note({ color: "blue" })
+// Result: { title: "My Note", content: "Hello", color: "blue" }
+```
+
+This is especially useful for large state objects where regenerating the entire state would be expensive and error-prone.
+
+<Callout type="info">
+  Merge is shallow (one level deep). If the AI sends a nested object, it replaces
+  that entire field rather than deep-merging into it.
+</Callout>
+
+## Multiple Instances
+
+You can render multiple interactables with the same `name` but different `id`s. Each gets its own update tool:
+
+```tsx
+import { useInteractable } from "@assistant-ui/react";
+import { z } from "zod";
+
+const noteSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  color: z.enum(["yellow", "blue", "green", "pink"]),
+});
+
+const noteInitialState = { title: "New Note", content: "", color: "yellow" as const };
+
+function NoteCard({ noteId }: { noteId: string }) {
+  const [state] = useInteractable("note", {
+    id: noteId,
+    description: "A sticky note",
+    stateSchema: noteSchema,
+    initialState: noteInitialState,
+  });
+
+  return <div>{state.title}</div>;
+}
+
+function App() {
+  return (
+    <>
+      <NoteCard noteId="note-1" /> {/* → update_note_note-1 tool */}
+      <NoteCard noteId="note-2" /> {/* → update_note_note-2 tool */}
+    </>
+  );
+}
+```
+
+When only one instance of a name exists, the tool is named `update_{name}` (e.g., `update_note`). When multiple instances exist, tools are named `update_{name}_{id}` (e.g., `update_note_note-1`).
+
+## Selection
+
+When multiple interactables are present, you can mark one as "selected" to tell the AI which one the user is focused on:
+
+```tsx
+function NoteCard({ noteId }: { noteId: string }) {
+  const [state, setState, { setSelected }] = useInteractable("note", {
+    id: noteId,
+    description: "A sticky note",
+    stateSchema: noteSchema,
+    initialState: noteInitialState,
+  });
+
+  return (
+    <div onClick={() => setSelected(true)}>
+      {state.title}
+    </div>
+  );
+}
+```
+
+The AI sees `(SELECTED)` in the system prompt for the focused interactable, allowing it to prioritize that one in responses. For example, the user can say _"Change the color to blue"_ and the AI knows which note to update.
+
+## API Reference
+
+### `useInteractable`
+
+Hook that registers an interactable and returns its state with a setter.
+
+```tsx
+const [state, setState, meta] = useInteractable<TState>(name, config);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Name for the interactable (used in tool names) |
+| `config.description` | `string` | Description shown to the AI |
+| `config.stateSchema` | `StandardSchemaV1 \| JSONSchema7` | Schema for the state (e.g., a Zod schema) |
+| `config.initialState` | `TState` | Initial state value |
+| `config.id` | `string?` | Optional unique instance ID (auto-generated if omitted) |
+| `config.selected` | `boolean?` | Whether this interactable is selected |
+
+**Returns:** `[state, setState, { id, setSelected }]`
+
+| Return | Type | Description |
+| --- | --- | --- |
+| `state` | `TState` | Current state |
+| `setState` | `(updater: TState \| (prev: TState) => TState) => void` | State setter (like `useState`) |
+| `meta.id` | `string` | The instance ID (auto-generated or provided) |
+| `meta.setSelected` | `(selected: boolean) => void` | Mark this interactable as selected |
+
+### `makeInteractable`
+
+Declarative API that creates a component which registers an interactable when mounted. Useful for static configurations.
+
+```tsx
+import { makeInteractable } from "@assistant-ui/react";
+
+const TaskBoardInteractable = makeInteractable({
+  name: "taskBoard",
+  description: "A task board showing the user's tasks",
+  stateSchema: taskBoardSchema,
+  initialState: taskBoardInitialState,
+});
+
+// Mount it anywhere — renders nothing, just registers the interactable
+function App() {
+  return (
+    <>
+      <TaskBoardInteractable />
+      <Thread />
+    </>
+  );
+}
+```
+
+### `Interactables`
+
+The scope resource that manages all interactables. Register it via `useAui`:
+
+```tsx
+const aui = useAui({
+  interactables: Interactables(),
+});
+```
+
+## How It Works
+
+When you call `useInteractable("taskBoard", config)`:
+
+1. **Registration** — the interactable is registered in the `interactables` scope with its name, description, schema, and initial state.
+2. **Tool generation** — an `update_taskBoard` frontend tool is automatically created with a partial schema (all fields optional). For multiple instances, tools are named `update_{name}_{id}`.
+3. **System prompt** — the AI receives a system message describing the interactable, its current state, and whether it is selected.
+4. **Streaming updates** — as the AI generates the tool arguments, the interactable's state updates progressively rather than waiting for complete arguments. This gives users immediate visual feedback.
+5. **Partial merge** — only the fields the AI sends are updated; the rest are preserved.
+6. **Bidirectional updates** — when the AI calls the tool, the state updates and React re-renders. When the user updates state via `setState`, the model context is notified so the AI sees the latest state on the next turn.
+
+## Combining with Tools
+
+You can use `Interactables` alongside `Tools`:
+
+```tsx
+const aui = useAui({
+  tools: Tools({ toolkit: myToolkit }),
+  interactables: Interactables(),
+});
+```

package/.docs/raw/docs/(docs)/guides/message-timing.mdx

@@ -58,8 +58,8 @@ const AssistantMessage: FC = () => {
 | `streamStartTime` | `number` | Unix timestamp when stream started |
 | `firstTokenTime` | `number?` | Time to first text token (ms) |
 | `totalStreamTime` | `number?` | Total stream duration (ms) |
-| `tokenCount` | `number?` | Real or estimated output token count |
-| `tokensPerSecond` | `number?` | Throughput (tokens/sec); see [accuracy note](#ai-sdk-usechatruntime) |
+| `tokenCount` | `number?` | Output token count from message metadata usage |
+| `tokensPerSecond` | `number?` | Throughput (tokens/sec), when token usage is available |
 | `totalChunks` | `number` | Total stream chunks received |
 | `toolCallCount` | `number` | Number of tool calls |
 
@@ -90,7 +90,7 @@ const runtime = useDataStreamRuntime({ api: "/api/chat" });
 Timing is tracked automatically on the client side by observing streaming state transitions and content changes. Timing is finalized when each stream completes.
 
 <Callout type="warn">
-  `tokenCount` and `tokensPerSecond` are **estimated** using a 4 characters per token approximation — real token counts from the server are not extracted. This can overcount significantly for short messages.
+  `tokenCount` and `tokensPerSecond` require usage metadata from `finish` or `finish-step` in your AI SDK route. If usage metadata is not emitted, duration and TTFT metrics still work, but token-based metrics are omitted.
 </Callout>
 
 ```tsx

package/.docs/raw/docs/(docs)/guides/multi-agent.mdx

@@ -171,3 +171,4 @@ function SubConversation({
 
 - [Generative UI](/docs/guides/tool-ui) — Creating tool call UIs
 - [MessagePartPrimitive](/docs/api-reference/primitives/message-part) — API reference for message part primitives
+- [Sub-Agent Model Tracking](/docs/cloud/ai-sdk#sub-agent-model-tracking) — Track delegated model usage and costs in the Cloud dashboard

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

@@ -415,3 +415,131 @@ import { AuiIf } from "@assistant-ui/react";
   {/* rendered if dictation is active */}
 </AuiIf>
 ```
+
+## Mention Primitives (Unstable)
+
+<Callout type="warn">
+  These primitives are under the `Unstable_` prefix and may change without notice.
+</Callout>
+
+Primitives for an @-mention picker in the composer. See the [Mention component guide](/docs/ui/mention) for a pre-built implementation.
+
+### Anatomy
+
+```tsx
+import { ComposerPrimitive } from "@assistant-ui/react";
+
+const Composer = () => (
+  <ComposerPrimitive.Unstable_MentionRoot adapter={mentionAdapter}>
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input />
+      <ComposerPrimitive.Unstable_MentionPopover>
+        <ComposerPrimitive.Unstable_MentionCategories>
+          {(categories) =>
+            categories.map((cat) => (
+              <ComposerPrimitive.Unstable_MentionCategoryItem
+                key={cat.id}
+                categoryId={cat.id}
+              >
+                {cat.label}
+              </ComposerPrimitive.Unstable_MentionCategoryItem>
+            ))
+          }
+        </ComposerPrimitive.Unstable_MentionCategories>
+        <ComposerPrimitive.Unstable_MentionItems>
+          {(items) =>
+            items.map((item) => (
+              <ComposerPrimitive.Unstable_MentionItem
+                key={item.id}
+                item={item}
+              >
+                {item.label}
+              </ComposerPrimitive.Unstable_MentionItem>
+            ))
+          }
+        </ComposerPrimitive.Unstable_MentionItems>
+        <ComposerPrimitive.Unstable_MentionBack>
+          Back
+        </ComposerPrimitive.Unstable_MentionBack>
+      </ComposerPrimitive.Unstable_MentionPopover>
+    </ComposerPrimitive.Root>
+  </ComposerPrimitive.Unstable_MentionRoot>
+);
+```
+
+### Unstable_MentionRoot
+
+Provider that wraps the composer with mention trigger detection, keyboard navigation, and popover state.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `adapter` | `Unstable_MentionAdapter` | — | Provides categories, items, and search |
+| `trigger` | `string` | `"@"` | Character(s) that activate the popover |
+| `formatter` | `Unstable_DirectiveFormatter` | Default | Serializer/parser for mention directives |
+
+### Unstable_MentionPopover
+
+Container that only renders when a mention trigger is active. Renders a `<div>` with `role="listbox"`.
+
+### Unstable_MentionCategories
+
+Renders the top-level category list. Accepts a render function `(categories) => ReactNode`. Hidden when a category is selected or when in search mode.
+
+### Unstable_MentionCategoryItem
+
+A button that drills into a category. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `categoryId` | `string` | The category to select on click |
+
+### Unstable_MentionItems
+
+Renders the item list for the active category or search results. Accepts a render function `(items) => ReactNode`. Hidden when no category is selected and not in search mode.
+
+### Unstable_MentionItem
+
+A button that inserts a mention into the composer. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `item` | `Unstable_MentionItem` | The item to insert on click |
+
+### Unstable_MentionBack
+
+A button that navigates back from items to the category list. Only renders when a category is active.
+
+### unstable_useMentionContext
+
+Hook to access the mention popover state and actions from within `Unstable_MentionRoot`.
+
+```tsx
+const {
+  open,           // boolean — whether popover is visible
+  query,          // string — text after the trigger character
+  isSearchMode,   // boolean — whether showing search results
+  highlightedIndex,
+  categories,
+  items,
+  activeCategoryId,
+  selectCategory,
+  selectItem,
+  goBack,
+  close,
+  handleKeyDown,
+  formatter,
+} = unstable_useMentionContext();
+```
+
+### unstable_useToolMentionAdapter
+
+Hook that creates a `Unstable_MentionAdapter` from registered tools (via `useAssistantTool`).
+
+```tsx
+import { unstable_useToolMentionAdapter } from "@assistant-ui/react";
+
+const adapter = unstable_useToolMentionAdapter({
+  formatLabel: (name) => name.replaceAll("_", " "),
+  categoryLabel: "Tools",
+});
+```

package/.docs/raw/docs/cloud/ai-sdk-assistant-ui.mdx

@@ -256,6 +256,12 @@ const cloud = new AssistantCloud({
 
 Return `null` from `beforeReport` to skip reporting a specific run. To disable telemetry entirely, pass `telemetry: false`.
 
+### Sub-Agent Model Tracking
+
+When tool calls delegate to a different model (e.g., the main run uses GPT but a tool invokes Gemini), you can track the delegated model's usage. Pass sampling call data through `messageMetadata.samplingCalls` in your API route, and the telemetry reporter will automatically include it in the report.
+
+See the [AI SDK Telemetry guide](/docs/cloud/ai-sdk#sub-agent-model-tracking) for the full setup with `createSamplingCollector` and `wrapSamplingHandler`.
+
 ## Authentication
 
 The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:

package/.docs/raw/docs/cloud/ai-sdk.mdx

@@ -252,7 +252,7 @@ export async function POST(req: Request) {
 ```
 
 <Callout type="info">
-  The standalone hook does not capture `duration_ms`, per-step breakdowns (`steps`), custom `metadata` pass-through, or `"error"` status. These require the full runtime integration available via [`useChatRuntime`](/docs/cloud/ai-sdk-assistant-ui).
+  The standalone hook captures message metadata when it is JSON-serializable, but it does not capture `duration_ms`, per-step breakdowns (`steps`), or `"error"` status. Those require the full runtime integration available via [`useChatRuntime`](/docs/cloud/ai-sdk-assistant-ui).
 </Callout>
 
 ### Customizing Reports
@@ -274,6 +274,86 @@ const cloud = new AssistantCloud({
 
 Return `null` from `beforeReport` to skip reporting a specific run. To disable telemetry entirely, pass `telemetry: false`.
 
+### Sub-Agent Model Tracking
+
+In multi-agent setups where tool calls delegate to a different model (e.g., the main run uses GPT but a tool invokes Gemini), you can track the delegated model's usage by passing sampling call data through `messageMetadata`.
+
+**Step 1: Collect sampling data on the server**
+
+Use `createSamplingCollector` and `wrapSamplingHandler` from `assistant-cloud` to capture LLM calls made during tool execution:
+
+```ts title="app/api/chat/route.ts"
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import {
+  createSamplingCollector,
+  wrapSamplingHandler,
+} from "assistant-cloud";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  // Collect sub-agent sampling calls per tool call
+  const samplingCalls: Record<string, SamplingCallData[]> = {};
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages,
+    tools: {
+      delegate_to_gemini: tool({
+        parameters: z.object({ task: z.string() }),
+        execute: async ({ task }, { toolCallId }) => {
+          const collector = createSamplingCollector();
+          // Your sub-agent logic that calls another model
+          const result = await runSubAgent(task, {
+            onSamplingCall: collector.collect,
+          });
+          samplingCalls[toolCallId] = collector.getCalls();
+          return result;
+        },
+      }),
+    },
+  });
+
+  return result.toUIMessageStreamResponse({
+    messageMetadata: ({ part }) => {
+      if (part.type === "finish") {
+        return {
+          usage: part.totalUsage,
+          samplingCalls, // attach collected sampling data
+        };
+      }
+      if (part.type === "finish-step") {
+        return { modelId: part.response.modelId };
+      }
+      return undefined;
+    },
+  });
+}
+```
+
+**Step 2: That's it.** The telemetry reporter automatically reads `samplingCalls` from message metadata and attaches the data to matching tool calls in the report. The Cloud dashboard will show each delegated model in the model distribution chart with its own token and cost breakdown.
+
+<Callout type="info">
+  For MCP tools that use the sampling protocol, `wrapSamplingHandler` can wrap the MCP client's sampling handler directly to capture all nested LLM calls transparently.
+</Callout>
+
+<Callout type="tip">
+  **On older versions** that don't yet read `samplingCalls` from metadata, use `beforeReport` to inject the data manually:
+
+  ```ts
+  telemetry: {
+    beforeReport: (report) => ({
+      ...report,
+      tool_calls: report.tool_calls?.map((tc) => ({
+        ...tc,
+        sampling_calls: samplingCalls[tc.tool_call_id],
+      })),
+    }),
+  }
+  ```
+</Callout>
+
 ## Authentication
 
 The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance: