@assistant-ui/mcp-docs-server 0.1.22 → 0.1.24

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

@@ -101,6 +101,59 @@ export default function Home() {
   </Step>
 </Steps>
 
+## Tracking Token Usage
+
+assistant-ui exports a `useThreadTokenUsage` hook to access thread-level token usage on the client.
+<Steps>
+  <Step>
+Use `messageMetadata` in your Next.js route to attach `usage` from `finish` and `modelId` from `finish-step`.
+```tsx
+import { streamText, convertToModelMessages } from "ai";
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+export async function POST(req: Request) {
+  const { messages, tools, modelName } = await req.json();
+  const result = streamText({
+    model: getModel(modelName),
+    messages: await convertToModelMessages(messages),
+    tools: frontendTools(tools),
+  });
+  return result.toUIMessageStreamResponse({
+    messageMetadata: ({ part }) => {
+      if (part.type === "finish") {
+        return {
+          usage: part.totalUsage,
+        };
+      }
+      if (part.type === "finish-step") {
+        return {
+          modelId: part.response.modelId,
+        };
+      }
+      return undefined;
+    },
+  });
+}
+```
+  </Step>
+  <Step>
+Use `useThreadTokenUsage` to render token usage on the client.
+
+```tsx
+"use client";
+
+import { useThreadTokenUsage } from "@assistant-ui/react-ai-sdk";
+
+export function TokenCounter() {
+  const usage = useThreadTokenUsage();
+
+  if (!usage) return null;
+
+  return <div>{usage.totalTokens} total tokens</div>;
+}
+```
+  </Step>
+</Steps>
+
 ## Key Changes from v5
 
 | Feature | v5 | v6 |
@@ -119,35 +172,27 @@ Creates a runtime integrated with AI SDK's `useChat` hook.
 ```tsx
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
-const runtime = useChatRuntime({
-  api: "/api/chat", // optional, defaults to "/api/chat"
-});
+const runtime = useChatRuntime();
 ```
 
 ### Custom API URL
 
-```tsx
-const runtime = useChatRuntime({
-  api: "/my-custom-api/chat",
-});
-```
-
-### Forwarding System Messages and Frontend Tools
-
-Use `AssistantChatTransport` to automatically forward system messages and frontend tools to your backend:
+To use a different endpoint, pass a custom `AssistantChatTransport`:
 
 ```tsx
-"use client";
-
 import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
 
 const runtime = useChatRuntime({
   transport: new AssistantChatTransport({
-    api: "/api/chat",
+    api: "/my-custom-api/chat",
   }),
 });
 ```
 
+### System Messages and Frontend Tools
+
+`AssistantChatTransport` (used by default) automatically forwards system messages and frontend tools to your backend. To consume them, update your backend route:
+
 Backend route with system/tools forwarding:
 
 ```tsx

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

@@ -114,6 +114,28 @@ async def chat_endpoint(request: ChatRequest):
 
 The state snapshots are automatically streamed to the frontend using the operations described in [Streaming Protocol](#streaming-protocol).
 
+> **Cancellation:** `create_run` exposes `controller.is_cancelled` and `controller.cancelled_event`.
+> If the response stream is closed early (for example user cancel or client disconnect),
+> these are set so your backend loop can exit cooperatively.
+> `controller.cancelled_event` is a read-only signal object with `wait()` and `is_set()`.
+> `create_run` gives callbacks a ~50ms cooperative shutdown window before forced task cancellation.
+> Callback exceptions that happen during early-close cleanup are not re-raised to the stream consumer,
+> but are logged with traceback at warning level for debugging.
+> Put critical cleanup in `finally` blocks, since forced cancellation may happen after the grace window.
+>
+> ```python
+> async def run_callback(controller: RunController):
+>     while not controller.is_cancelled:
+>         # Long-running work / model loop
+>         await asyncio.sleep(0.05)
+> ```
+>
+> ```python
+> async def run_callback(controller: RunController):
+>     await controller.cancelled_event.wait()
+>     # cancellation-aware shutdown path
+> ```
+
 ### Backend Reference Implementation
 
 <Tabs items={["Minimal", "Example", "LangGraph"]}>
@@ -314,6 +336,8 @@ The `useAssistantTransportRuntime` hook is used to configure the runtime. It acc
   converter: (state: T, connectionMetadata: ConnectionMetadata) => AssistantTransportState,
   headers?: Record<string, string> | (() => Promise<Record<string, string>>),
   body?: object,
+  prepareSendCommandsRequest?: (body: SendCommandsRequestBody) => Record<string, unknown> | Promise<Record<string, unknown>>,
+  capabilities?: { edit?: boolean },
   onResponse?: (response: Response) => void,
   onFinish?: () => void,
   onError?: (error: Error) => void,
@@ -490,6 +514,85 @@ const runtime = useAssistantTransportRuntime({
 });
 ```
 
+### Transforming the Request Body
+
+Use `prepareSendCommandsRequest` to transform the entire request body before it is sent to the backend. This receives the fully assembled body object and returns the (potentially transformed) body.
+
+```typescript
+const runtime = useAssistantTransportRuntime({
+  // ... other options
+  prepareSendCommandsRequest: (body) => ({
+    ...body,
+    trackingId: crypto.randomUUID(),
+  }),
+});
+```
+
+This is useful for adding tracking IDs, transforming commands, or injecting metadata that depends on the assembled request:
+
+```typescript
+const runtime = useAssistantTransportRuntime({
+  // ... other options
+  prepareSendCommandsRequest: (body) => ({
+    ...body,
+    commands: body.commands.map((cmd) =>
+      cmd.type === "add-message"
+        ? { ...cmd, trackingId: crypto.randomUUID() }
+        : cmd,
+    ),
+  }),
+});
+```
+
+## Editing Messages
+
+By default, editing messages is disabled. To enable it, set `capabilities.edit` to `true`:
+
+```typescript
+const runtime = useAssistantTransportRuntime({
+  // ... other options
+  capabilities: {
+    edit: true,
+  },
+});
+```
+
+`add-message` commands always include `parentId` and `sourceId` fields:
+
+```typescript
+{
+  type: "add-message",
+  message: { role: "user", parts: [...] },
+  parentId: "msg-3",  // The message after which this message should be inserted
+  sourceId: "msg-4",  // The ID of the message being replaced (null for new messages)
+}
+```
+
+### Backend Handling
+
+When the backend receives an `add-message` command with a `parentId`, it should:
+
+1. Truncate all messages after the message with `parentId`
+2. Append the new message
+3. Stream the updated state back to the frontend
+
+```python
+for command in request.commands:
+    if command.type == "add-message":
+        if hasattr(command, "parentId") and command.parentId is not None:
+            # Find the parent message index and truncate
+            parent_idx = next(
+                i for i, m in enumerate(messages) if m.id == command.parentId
+            )
+            messages = messages[:parent_idx + 1]
+        # Append the new message
+        messages.append(command.message)
+```
+
+<Callout type="info">
+  `parentId` and `sourceId` are always included on `add-message` commands. For new messages, `sourceId` will be `null`.
+</Callout>
+
 ## Resuming from a Sync Server
 
 <Callout type="info">

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -1157,6 +1157,29 @@ const ToolUI = makeAssistantToolUI({
 });
 ```
 
+### Binding External Messages Manually
+
+Use `bindExternalStoreMessage` to attach your original message to a `ThreadMessage` or message part object. This is useful when you construct `ThreadMessage` objects yourself (outside of the built-in message converter) and want `getExternalStoreMessages` to work with them.
+
+```tsx
+import {
+  bindExternalStoreMessage,
+  getExternalStoreMessages,
+} from "@assistant-ui/react";
+
+// Attach your original message to a ThreadMessage
+bindExternalStoreMessage(threadMessage, originalMessage);
+
+// Later, retrieve it
+const original = getExternalStoreMessages(threadMessage);
+```
+
+<Callout type="warn">
+  This API is experimental and may change without notice.
+</Callout>
+
+`bindExternalStoreMessage` is a no-op if the target already has a bound message. It mutates the target object in place.
+
 ## Debugging
 
 ### Common Debugging Scenarios
@@ -1503,7 +1526,7 @@ A flexible message format that can be converted to assistant-ui's internal forma
     {
       name: "content",
       type: "string | readonly MessagePart[]",
-      description: "Message content as string or structured message parts",
+      description: "Message content as string or structured message parts. Supports `data-*` prefixed types (e.g. `{ type: \"data-workflow\", data: {...} }`) which are automatically converted to DataMessagePart.",
       required: true,
     },
     {
@@ -1525,7 +1548,7 @@ A flexible message format that can be converted to assistant-ui's internal forma
     {
       name: "attachments",
       type: "readonly CompleteAttachment[]",
-      description: "File attachments (user messages only)",
+      description: "File attachments (user messages only). Attachment `type` accepts custom strings beyond \"image\" | \"document\" | \"file\", and `contentType` is optional.",
     },
     {
       name: "metadata",

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

@@ -342,9 +342,7 @@ const runtime = useDataStreamRuntime({
 
 ## Examples
 
-- **[Basic Data Stream Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream)** - Simple streaming chat
-- **[Tool Integration Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream-tools)** - Frontend and backend tools
-- **[Authentication Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream-auth)** - Secure endpoints
+Explore our [examples repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples) for implementation references.
 
 ## API Reference
 

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

@@ -158,19 +158,21 @@ export const getThreadState = async (
 
 export const sendMessage = async (params: {
   threadId: string;
-  messages: LangChainMessage;
+  messages: LangChainMessage[];
   config?: LangGraphSendMessageConfig;
 }) => {
   const client = createClient();
+  const { checkpointId, ...restConfig } = params.config ?? {};
   return client.runs.stream(
     params.threadId,
     process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
     {
-      input: {
-        messages: params.messages,
-      },
-      streamMode: "messages",
-      ...params.config
+      input: params.messages.length > 0
+        ? { messages: params.messages }
+        : null,
+      streamMode: "messages-tuple",
+      ...(checkpointId && { checkpoint_id: checkpointId }),
+      ...restConfig,
     },
   );
 };
@@ -196,7 +198,7 @@ import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
 
 export function MyAssistant() {
   const runtime = useLangGraphRuntime({
-    stream: async (messages, { initialize, config }) => {
+    stream: async (messages, { initialize, ...config }) => {
       const { externalId } = await initialize();
       if (!externalId) throw new Error("Thread not found");
       return sendMessage({
@@ -300,6 +302,44 @@ import { convertLangChainMessages } from "@assistant-ui/react-langgraph";
 const threadMessage = convertLangChainMessages(langChainMessage);
 ```
 
+### Event Handlers
+
+You can listen to streaming events by passing `eventHandlers` to `useLangGraphRuntime`:
+
+```typescript
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => { /* ... */ },
+  eventHandlers: {
+    onMessageChunk: (chunk, metadata) => {
+      // Fired for each chunk in messages-tuple mode
+      // metadata contains langgraph_step, langgraph_node, ls_model_name, etc.
+    },
+    onValues: (values) => {
+      // Fired when a "values" event is received
+    },
+    onUpdates: (updates) => {
+      // Fired when an "updates" event is received
+    },
+    onMetadata: (metadata) => { /* thread metadata */ },
+    onError: (error) => { /* stream errors */ },
+    onCustomEvent: (type, data) => { /* custom events */ },
+  },
+});
+```
+
+### Message Metadata
+
+When using `streamMode: "messages-tuple"`, each chunk includes metadata from the LangGraph server. Access accumulated metadata per message with the `useLangGraphMessageMetadata` hook:
+
+```typescript
+import { useLangGraphMessageMetadata } from "@assistant-ui/react-langgraph";
+
+function MyComponent() {
+  const metadata = useLangGraphMessageMetadata();
+  // Map<string, LangGraphTupleMetadata> keyed by message ID
+}
+```
+
 ## Thread Management
 
 ### Basic Thread Support
@@ -308,7 +348,7 @@ The `useLangGraphRuntime` hook now includes built-in thread management capabilit
 
 ```typescript
 const runtime = useLangGraphRuntime({
-  stream: async (messages, { initialize, config }) => {
+  stream: async (messages, { initialize, ...config }) => {
     // initialize() creates or loads a thread and returns its IDs
     const { remoteId, externalId } = await initialize();
     // Use externalId (your backend's thread ID) for API calls
@@ -343,7 +383,71 @@ const runtime = useLangGraphRuntime({
 });
 ```
 
-See the [Cloud Persistence guide](/docs/cloud/persistence/langgraph) for detailed setup instructions.
+See the [Cloud Persistence guide](/docs/cloud/langgraph) for detailed setup instructions.
+
+## Message Editing & Regeneration
+
+LangGraph uses server-side checkpoints for state management. To support message editing (branching) and regeneration, you need to provide a `getCheckpointId` callback that resolves the appropriate checkpoint for server-side forking.
+
+```typescript
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => {
+    const { externalId } = await initialize();
+    if (!externalId) throw new Error("Thread not found");
+    return sendMessage({ threadId: externalId, messages, config });
+  },
+  create: async () => {
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+  load: async (externalId) => {
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+  getCheckpointId: async (threadId, parentMessages) => {
+    const client = createClient();
+    // Get the thread state history and find the checkpoint
+    // that matches the parent messages by exact message ID sequence.
+    // If IDs are missing, return null and skip edit/reload for safety.
+    const history = await client.threads.getHistory(threadId);
+    for (const state of history) {
+      const stateMessages = state.values.messages;
+      if (!stateMessages || stateMessages.length !== parentMessages.length) {
+        continue;
+      }
+
+      const hasStableIds =
+        parentMessages.every((message) => typeof message.id === "string") &&
+        stateMessages.every((message) => typeof message.id === "string");
+      if (!hasStableIds) {
+        continue;
+      }
+
+      const isMatch = parentMessages.every(
+        (message, index) => message.id === stateMessages[index]?.id,
+      );
+
+      if (isMatch) {
+        return state.checkpoint.checkpoint_id ?? null;
+      }
+    }
+    return null;
+  },
+});
+```
+
+When `getCheckpointId` is provided:
+- **Edit buttons** appear on user messages, allowing users to edit and resend from that point
+- **Regenerate buttons** appear on assistant messages, allowing users to regenerate the response
+
+The resolved `checkpointId` is passed to your `stream` callback via `config.checkpointId`. Your `sendMessage` helper should map it to the LangGraph SDK's `checkpoint_id` parameter (see the helper function in the setup section above).
+
+<Callout type="info">
+  Without `getCheckpointId`, the edit and regenerate buttons will not appear. This is intentional — simply truncating client-side messages without forking from the correct server-side checkpoint would produce incorrect state.
+</Callout>
 
 ## Interrupt Persistence
 

package/.docs/raw/docs/runtimes/pick-a-runtime.mdx

@@ -130,9 +130,7 @@ Pre-built integrations can always be replaced with a custom `LocalRuntime` or `E
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 export function MyAssistant() {
-  const runtime = useChatRuntime({
-    api: "/api/chat",
-  });
+  const runtime = useChatRuntime();
 
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -189,7 +187,6 @@ Explore our implementation examples:
 - **[External Store Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-external-store)** - `ExternalStoreRuntime` with custom state
 - **[Assistant Cloud Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud)** - Multi-thread with cloud persistence
 - **[LangGraph Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)** - Agent workflows
-- **[OpenAI Assistants Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-openai-assistants)** - OpenAI Assistants API
 
 ## Common Pitfalls to Avoid
 

package/.docs/raw/docs/ui/attachment.mdx

@@ -209,9 +209,9 @@ Attachments have the following structure:
 ```typescript
 type Attachment = {
   id: string;
-  type: "image" | "document" | "file";
+  type: "image" | "document" | "file" | (string & {});
   name: string;
-  contentType: string;
+  contentType?: string;
   file?: File;
   status:
     | { type: "running" | "requires-action" | "incomplete"; progress?: number }
@@ -219,6 +219,8 @@ type Attachment = {
 };
 ```
 
+The `type` field accepts custom strings (e.g. `"data-workflow"`) beyond the built-in types. When an unknown type is encountered, the generic `Attachment` component is used as a fallback. The `contentType` field is optional — it can be omitted for non-file attachments where a MIME type is not meaningful.
+
 ## Related Components
 
 - [Thread](/docs/ui/thread) - Main chat interface that displays attachments

package/.docs/raw/docs/ui/context-display.mdx

@@ -0,0 +1,147 @@
+---
+title: Context Display
+description: Visualize token usage relative to a model's context window — ring, bar, or text — with a detailed hover popover.
+---
+
+import { ContextDisplaySample } from "@/components/docs/samples/context-display";
+
+<ContextDisplaySample />
+
+<Callout type="info">
+  This component requires server-side setup to [forward token usage metadata](#forward-token-usage-from-your-route-handler). Without it, ContextDisplay will show 0 usage and no breakdown data.
+</Callout>
+
+## Getting Started
+
+<Steps>
+  <Step>
+
+### Add `context-display`
+
+<InstallCommand shadcn={["context-display"]} />
+
+This adds a `/components/assistant-ui/context-display.tsx` file to your project.
+
+  </Step>
+  <Step>
+
+### Forward token usage from your route handler
+
+Use `messageMetadata` in your Next.js route to attach `usage` from `finish` and `modelId` from `finish-step`:
+
+```tsx title="app/api/chat/route.ts"
+import { streamText, convertToModelMessages } from "ai";
+
+export async function POST(req: Request) {
+  const { messages, modelName } = await req.json();
+  const result = streamText({
+    model: getModel(modelName),
+    messages: await convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse({
+    messageMetadata: ({ part }) => {
+      if (part.type === "finish") {
+        return {
+          usage: part.totalUsage,
+        };
+      }
+      if (part.type === "finish-step") {
+        return {
+          modelId: part.response.modelId,
+        };
+      }
+      return undefined;
+    },
+  });
+}
+```
+
+  </Step>
+  <Step>
+
+### Use in your application
+
+Pick a variant and place it in your thread footer, composer, or sidebar. Pass `modelContextWindow` with your model's token limit.
+
+```tsx title="/components/assistant-ui/thread.tsx" {1,8}
+import { ContextDisplay } from "@/components/assistant-ui/context-display";
+
+const ThreadFooter: FC = () => {
+  return (
+    <div className="flex items-center justify-end px-3 py-1.5">
+      <ContextDisplay.Bar modelContextWindow={128000} />
+    </div>
+  );
+};
+```
+
+  </Step>
+</Steps>
+
+## Variants
+
+Three preset variants are available, each wrapping the shared tooltip popover:
+
+```tsx
+// SVG donut ring (default, compact)
+<ContextDisplay.Ring modelContextWindow={128000} />
+
+// Horizontal progress bar with label
+<ContextDisplay.Bar modelContextWindow={128000} />
+
+// Minimal monospace text
+<ContextDisplay.Text modelContextWindow={128000} />
+```
+
+All presets accept `className` for styling overrides and `side` to control tooltip placement (`"top"`, `"bottom"`, `"left"`, `"right"`).
+
+## Composable API
+
+For custom visualizations, use the building blocks directly:
+
+```tsx
+import { ContextDisplay } from "@/components/assistant-ui/context-display";
+
+<ContextDisplay.Root modelContextWindow={128000}>
+  <ContextDisplay.Trigger aria-label="Context usage">
+    <MyCustomGauge />
+  </ContextDisplay.Trigger>
+  <ContextDisplay.Content side="top" />
+</ContextDisplay.Root>
+```
+
+| Component | Description |
+|-----------|-------------|
+| `Root` | Uses provided `usage` when supplied, otherwise fetches token usage internally; provides shared context and wraps children in a tooltip |
+| `Trigger` | Button that opens the tooltip on hover |
+| `Content` | Tooltip popover with the token breakdown (Usage %, Input, Cached, Output, Reasoning, Total) |
+
+## API Reference
+
+### Preset Props
+
+All preset variants (`Ring`, `Bar`, `Text`) share the same props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelContextWindow` | `number` | — | Maximum token limit of the current model (required) |
+| `className` | `string` | — | Additional class names on the trigger button |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Tooltip placement |
+| `usage` | `ThreadTokenUsage` | — | Optional externally-provided usage data (skips internal usage fetch when provided) |
+
+### Color Thresholds
+
+Ring and Bar share the same severity colors:
+
+| Level | Threshold | Ring | Bar |
+|-------|-----------|------|-----|
+| Low | `< 65%` | `stroke-emerald-500` | `bg-emerald-500` |
+| Warning | `65% – 85%` | `stroke-amber-500` | `bg-amber-500` |
+| Critical | `> 85%` | `stroke-red-500` | `bg-red-500` |
+
+Text displays numeric values only — no severity color.
+
+## Related
+
+- [Message Timing](/docs/ui/message-timing) — Streaming performance stats (TTFT, tok/s)
+- [Thread](/docs/ui/thread) — The thread component where ContextDisplay is typically placed