@assistant-ui/mcp-docs-server 0.1.9 → 0.1.11

package/.docs/raw/docs/migrations/react-langgraph-v0-7.mdx

@@ -0,0 +1,324 @@
+---
+title: Migrating to react-langgraph v0.7
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+import { Steps, Step } from "fumadocs-ui/components/steps";
+
+## Overview
+
+This guide helps you migrate from the previous LangGraph integration pattern to the new simplified API introduced in `@assistant-ui/react-langgraph` v0.7. The new API consolidates thread management directly into `useLangGraphRuntime`, eliminating the need for separate runtime hooks and manual thread state management.
+
+## Key Changes
+
+### 1. Simplified Thread Management
+
+The `useLangGraphRuntime` hook now directly handles thread lifecycle:
+- No more `useRemoteThreadListRuntime` wrapper
+- No more separate runtime hook functions
+- Thread management is built into the core runtime
+
+### 2. New `initialize` Parameter
+
+The `stream` function now receives an `initialize` parameter that handles thread creation and loading automatically.
+
+### 3. Direct Cloud Integration
+
+Cloud persistence can now be configured directly in `useLangGraphRuntime` with the `cloud` parameter.
+
+## Migration Steps
+
+<Steps>
+
+<Step>
+
+### Update Your Runtime Implementation
+
+#### Before (Old Pattern)
+
+```tsx
+import {
+  useCloudThreadListRuntime,
+  useThreadListItemRuntime,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+const useMyLangGraphRuntime = () => {
+  const threadListItemRuntime = useThreadListItemRuntime();
+
+  const runtime = useLangGraphRuntime({
+    stream: async function* (messages) {
+      const { externalId } = await threadListItemRuntime.initialize();
+      if (!externalId) throw new Error("Thread not found");
+
+      return sendMessage({
+        threadId: externalId,
+        messages,
+      });
+    },
+    onSwitchToThread: async (externalId) => {
+      const state = await getThreadState(externalId);
+      return {
+        messages: state.values.messages,
+      };
+    },
+  });
+
+  return runtime;
+};
+
+// In your component:
+const runtime = useCloudThreadListRuntime({
+  cloud,
+  runtimeHook: useMyLangGraphRuntime,
+  create: async () => {
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+});
+```
+
+#### After (New Pattern)
+
+```tsx
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+// Directly in your component:
+const runtime = useLangGraphRuntime({
+  cloud, // Optional: for cloud persistence
+  stream: async function* (messages, { initialize }) {
+    const { externalId } = await initialize();
+    if (!externalId) throw new Error("Thread not found");
+
+    return sendMessage({
+      threadId: externalId,
+      messages,
+    });
+  },
+  create: async () => {
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+  load: async (externalId) => {
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+    };
+  },
+});
+```
+
+</Step>
+
+<Step>
+
+### Update Import Statements
+
+Remove unused imports:
+
+```diff
+- import {
+-   useCloudThreadListRuntime,
+-   useThreadListItemRuntime,
+- } from "@assistant-ui/react";
++ import { AssistantCloud } from "@assistant-ui/react";
+```
+
+</Step>
+
+<Step>
+
+### Simplify Component Structure
+
+You no longer need a separate runtime hook function. Everything can be defined directly in your component or provider:
+
+```tsx
+export function MyRuntimeProvider({ children }) {
+  const cloud = useMemo(
+    () => new AssistantCloud({
+      baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
+    }),
+    []
+  );
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    // All configuration inline
+    stream: async function* (messages, { initialize }) {
+      // Your stream implementation
+    },
+    create: async () => {
+      // Your create implementation
+    },
+    load: async (externalId) => {
+      // Your load implementation
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Step>
+
+<Step>
+
+### Update Method Names
+
+Rename methods to match the new API:
+
+- `onSwitchToThread` → `load`
+- `onSwitchToNewThread` → handled automatically via `create`
+- Thread ID management is now automatic
+
+</Step>
+
+</Steps>
+
+## API Reference Changes
+
+### Old API
+
+```typescript
+type OldLangGraphRuntimeOptions = {
+  threadId?: string;
+  stream: (messages: Message[]) => AsyncGenerator;
+  onSwitchToNewThread?: () => Promise<void>;
+  onSwitchToThread?: (threadId: string) => Promise<ThreadState>;
+};
+```
+
+### New API
+
+```typescript
+type NewLangGraphRuntimeOptions = {
+  cloud?: AssistantCloud;
+  stream: (
+    messages: Message[],
+    context: {
+      initialize: () => Promise<{
+        remoteId: string;
+        externalId: string | undefined;
+      }>
+    }
+  ) => AsyncGenerator;
+  create?: () => Promise<{ externalId: string }>;
+  load?: (externalId: string) => Promise<ThreadState>;
+  delete?: (externalId: string) => Promise<void>;
+};
+```
+
+## Benefits of the New API
+
+1. **Simpler Setup**: No need for multiple runtime hooks and wrappers
+2. **Cleaner Code**: All configuration in one place
+3. **Better Type Safety**: More explicit types for thread management
+4. **Automatic Thread Handling**: The runtime manages thread lifecycle internally
+5. **Optional Cloud Integration**: Add cloud persistence with a single parameter
+
+## Common Migration Issues
+
+<Callout type="warning">
+  **Breaking Change**: The `threadId` and `onSwitchToNewThread` parameters are no longer supported. Use the new `create` and `load` methods instead.
+</Callout>
+
+### Issue: `threadListItemRuntime` is not defined
+
+**Solution**: Remove references to `useThreadListItemRuntime()`. Use the `initialize` parameter in the stream function instead.
+
+### Issue: Thread switching doesn't work
+
+**Solution**: Ensure you've implemented both `create` and `load` functions. The runtime needs both to manage thread lifecycle.
+
+### Issue: Cloud persistence not working
+
+**Solution**: Pass the `AssistantCloud` instance directly to `useLangGraphRuntime` via the `cloud` parameter.
+
+## Example: Complete Migration
+
+Here's a complete before and after example for a typical LangGraph integration:
+
+### Before
+
+```tsx title="runtime-provider.tsx"
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+  useCloudThreadListRuntime,
+  useThreadListItemRuntime,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+const useMyRuntime = () => {
+  const threadListItemRuntime = useThreadListItemRuntime();
+
+  return useLangGraphRuntime({
+    stream: async function* (messages) {
+      const { externalId } = await threadListItemRuntime.initialize();
+      // ... implementation
+    },
+    onSwitchToThread: async (externalId) => {
+      // ... implementation
+    },
+  });
+};
+
+export function Provider({ children }) {
+  const cloud = new AssistantCloud({ /* config */ });
+
+  const runtime = useCloudThreadListRuntime({
+    cloud,
+    runtimeHook: useMyRuntime,
+    create: async () => { /* ... */ },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+### After
+
+```tsx title="runtime-provider.tsx"
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+export function Provider({ children }) {
+  const cloud = new AssistantCloud({ /* config */ });
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    stream: async function* (messages, { initialize }) {
+      const { externalId } = await initialize();
+      // ... implementation
+    },
+    create: async () => { /* ... */ },
+    load: async (externalId) => {
+      // ... implementation (formerly onSwitchToThread)
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+## Need Help?
+
+If you encounter issues during migration:
+1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph)
+2. Review the [example implementation](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)
+3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)

package/.docs/raw/docs/runtimes/ai-sdk/use-chat.mdx

@@ -41,7 +41,7 @@ npm install @assistant-ui/react @assistant-ui/react-ai-sdk ai @ai-sdk/openai
 ```tsx
 import { openai } from "@ai-sdk/openai";
 import { streamText, UIMessage, convertToModelMessages, tool } from "ai";
-import { frontendTools } from "@assistant-ui/assistant-stream/ai-sdk";
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
 import { z } from "zod";
 
 // Allow streaming responses up to 30 seconds
@@ -173,7 +173,7 @@ const runtime = useChatRuntime({
 When using `AssistantChatTransport`, frontend tools are forwarded to your backend. Use the `frontendTools` helper to properly integrate them:
 
 ```tsx
-import { frontendTools } from "@assistant-ui/assistant-stream/ai-sdk";
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
 
 export async function POST(req: Request) {
   const { messages, system, tools } = await req.json();

package/.docs/raw/docs/runtimes/custom/custom-thread-list.mdx

@@ -0,0 +1,218 @@
+---
+title: Custom Thread List
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+import { Steps, Step } from "fumadocs-ui/components/steps";
+import { ParametersTable } from "@/components/docs";
+
+## Overview
+
+`useRemoteThreadListRuntime` lets you plug a custom thread database into assistant-ui. It keeps the UI and local runtime logic in sync while you provide persistence, archiving, and metadata for every conversation. The hook is exported as `unstable_useRemoteThreadListRuntime`; we refer to it here as **Custom Thread List**.
+
+## When to Use
+
+Use a Custom Thread List when you need to:
+
+- Persist conversations in your own database or multitenant backend
+- Share threads across devices, teams, or long-lived sessions
+- Control thread metadata (titles, archived state, external identifiers)
+- Layer additional adapters (history, attachments) around each thread runtime
+
+## How It Works
+
+Custom Thread List merges two pieces of state:
+
+1. **Per-thread runtime** – powered by any runtime hook (for example `useLocalRuntime` or `useAssistantTransportRuntime`).
+2. **Thread list adapter** – your adapter that reads and writes thread metadata in a remote store.
+
+When the hook mounts it calls `list()` on your adapter, hydrates existing threads, and uses your runtime hook to spawn a runtime whenever a thread is opened. Creating a new conversation calls `initialize(threadId)` so you can create a record server-side and return the canonical `remoteId`.
+
+<Callout type="info">
+  The built-in Assistant Cloud runtime is implemented with the same API. Inspect
+  `useCloudThreadListAdapter` for a production-ready reference adapter.
+</Callout>
+
+## Build a Custom Thread List
+
+<Steps>
+  <Step>
+    ### Provide a runtime per thread
+
+    Use any runtime hook that returns an `AssistantRuntime`. In most custom setups this is `useLocalRuntime(modelAdapter)` or `useAssistantTransportRuntime(...)`.
+
+  </Step>
+  <Step>
+    ### Implement the adapter contract
+
+    Your adapter decides how threads are stored. Implement the methods in the table below to connect to your database or API.
+
+  </Step>
+  <Step>
+    ### Compose the provider
+
+    Wrap `AssistantRuntimeProvider` with the runtime returned from the Custom Thread List hook.
+
+    ```tsx twoslash title="app/CustomThreadListProvider.tsx"
+    // @filename: app/model-adapter.ts
+    export const myModelAdapter = {} as any;
+
+    // @filename: app/CustomThreadListProvider.tsx
+    // ---cut---
+    "use client";
+
+    import type { ReactNode } from "react";
+    import {
+      AssistantRuntimeProvider,
+      useLocalRuntime,
+      unstable_useRemoteThreadListRuntime as useRemoteThreadListRuntime,
+      type unstable_RemoteThreadListAdapter as RemoteThreadListAdapter,
+    } from "@assistant-ui/react";
+    import { createAssistantStream } from "assistant-stream";
+    import { myModelAdapter } from "./model-adapter"; // your chat model adapter
+
+    const threadListAdapter: RemoteThreadListAdapter = {
+      async list() {
+        const response = await fetch("/api/threads");
+        const threads = await response.json();
+        return {
+          threads: threads.map((thread: any) => ({
+            remoteId: thread.id,
+            externalId: thread.external_id ?? undefined,
+            status: thread.is_archived ? "archived" : "regular",
+            title: thread.title ?? undefined,
+          })),
+        };
+      },
+      async initialize(localId) {
+        const response = await fetch("/api/threads", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ localId }),
+        });
+        const result = await response.json();
+        return { remoteId: result.id, externalId: result.external_id };
+      },
+      async rename(remoteId, title) {
+        await fetch(`/api/threads/${remoteId}`, {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ title }),
+        });
+      },
+      async archive(remoteId) {
+        await fetch(`/api/threads/${remoteId}/archive`, { method: "POST" });
+      },
+      async unarchive(remoteId) {
+        await fetch(`/api/threads/${remoteId}/unarchive`, { method: "POST" });
+      },
+      async delete(remoteId) {
+        await fetch(`/api/threads/${remoteId}`, { method: "DELETE" });
+      },
+      async generateTitle(remoteId, messages) {
+        return createAssistantStream(async (controller) => {
+          const response = await fetch(`/api/threads/${remoteId}/title`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ messages }),
+          });
+          const { title } = await response.json();
+          controller.appendText(title);
+        });
+      },
+    };
+
+    export function CustomThreadListProvider({
+      children,
+    }: Readonly<{ children: ReactNode }>) {
+      const runtime = useRemoteThreadListRuntime({
+        runtimeHook: () => useLocalRuntime(myModelAdapter),
+        adapter: threadListAdapter,
+      });
+
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          {children}
+        </AssistantRuntimeProvider>
+      );
+    }
+    ```
+
+  </Step>
+</Steps>
+
+## Adapter Responsibilities
+
+<ParametersTable
+  type="RemoteThreadListAdapter"
+  parameters={[
+    {
+      name: "list",
+      type: "() => Promise<{ threads: RemoteThreadMetadata[] }>",
+      description:
+        "Return the current threads. Each thread must include status, remoteId, and any metadata you want to show immediately.",
+      required: true,
+    },
+    {
+      name: "initialize",
+      type: "(localId: string) => Promise<{ remoteId: string; externalId?: string }>",
+      description:
+        "Create a new remote record when the user starts a conversation. Return the canonical ids so later operations target the right thread.",
+      required: true,
+    },
+    {
+      name: "rename",
+      type: "(remoteId: string, title: string) => Promise<void>",
+      description: "Persist title changes triggered from the UI.",
+      required: true,
+    },
+    {
+      name: "archive",
+      type: "(remoteId: string) => Promise<void>",
+      description: "Mark the thread as archived in your system.",
+      required: true,
+    },
+    {
+      name: "unarchive",
+      type: "(remoteId: string) => Promise<void>",
+      description: "Restore an archived thread to the active list.",
+      required: true,
+    },
+    {
+      name: "delete",
+      type: "(remoteId: string) => Promise<void>",
+      description: "Permanently remove the thread and stop rendering it.",
+      required: true,
+    },
+    {
+      name: "generateTitle",
+      type: "(remoteId: string, unstable_messages: readonly ThreadMessage[]) => Promise<AssistantStream>",
+      description:
+        "Return a streaming title generator. You can reuse your model endpoint or queue a background job.",
+      required: true,
+    },
+    {
+      name: "unstable_Provider",
+      type: "ComponentType<PropsWithChildren>",
+      description:
+        "Optional wrapper rendered around all thread runtimes. Use it to inject adapters such as history or attachments (see the Cloud adapter).",
+    },
+  ]}
+/>
+
+## Thread Lifecycle Cheatsheet
+
+- `list()` hydrates threads on mount and during refreshes.
+- Creating a new conversation calls `initialize()` once the user sends the first message.
+- `archive`, `unarchive`, and `delete` are called optimistically; throw to revert the UI.
+- `generateTitle()` powers the automatic title button and expects an `AssistantStream`.
+- Provide a `runtimeHook` that always returns a fresh runtime instance per active thread.
+
+## Optional Adapters
+
+If you need history or attachment support, expose them via `unstable_Provider`. The cloud implementation wraps each thread runtime with `RuntimeAdapterProvider` to inject:
+
+- `history` – e.g. `useAssistantCloudThreadHistoryAdapter`
+- `attachments` – e.g. `CloudFileAttachmentAdapter`
+
+Reuse that pattern to register any capability your runtime requires.

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

@@ -164,45 +164,52 @@ graph TD
     ```tsx title="app/MyRuntimeProvider.tsx"
     "use client";
 
-    import { useState } from "react";
+    import { ThreadMessageLike } from "@assistant-ui/react";
+    import { AppendMessage } from "@assistant-ui/react";
     import {
-      useExternalStoreRuntime,
-      ThreadMessageLike,
-      AppendMessage,
       AssistantRuntimeProvider,
+      useExternalStoreRuntime,
     } from "@assistant-ui/react";
-
-    export function MyRuntimeProvider({ children }) {
-      const [messages, setMessages] = useState<ThreadMessageLike[]>([]);
-      const [isRunning, setIsRunning] = useState(false);
-
+    import { useState } from "react";
+    
+    const convertMessage = (message: ThreadMessageLike) => {
+      return message;
+    };
+    
+    export function MyRuntimeProvider({
+      children,
+    }: Readonly<{
+      children: React.ReactNode;
+    }>) {
+      const [messages, setMessages] = useState<readonly ThreadMessageLike[]>([]);
+    
       const onNew = async (message: AppendMessage) => {
-        // Add user message
+        if (message.content.length !== 1 || message.content[0]?.type !== "text")
+          throw new Error("Only text content is supported");
+    
         const userMessage: ThreadMessageLike = {
           role: "user",
-          content: message.content,
+          content: [{ type: "text", text: message.content[0].text }],
         };
-        setMessages(prev => [...prev, userMessage]);
-
-        // Generate response
-        setIsRunning(true);
-        const response = await callYourAPI(message);
-
+        setMessages((currentMessages) => [...currentMessages, userMessage]);
+    
+        // normally you would perform an API call here to get the assistant response
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    
         const assistantMessage: ThreadMessageLike = {
           role: "assistant",
-          content: response.content,
+          content: [{ type: "text", text: "Hello, world!" }],
         };
-        setMessages(prev => [...prev, assistantMessage]);
-        setIsRunning(false);
+        setMessages((currentMessages) => [...currentMessages, assistantMessage]);
       };
-
-      const runtime = useExternalStoreRuntime({
+    
+      const runtime = useExternalStoreRuntime<ThreadMessageLike>({
         messages,
         setMessages,
-        isRunning,
         onNew,
+        convertMessage,
       });
-
+    
       return (
         <AssistantRuntimeProvider runtime={runtime}>
           {children}