@assistant-ui/mcp-docs-server 0.1.39 → 0.2.0

package/.docs/raw/docs/guides/electron.mdx

@@ -0,0 +1,369 @@
+---
+title: Electron
+description: Run assistant-ui in an Electron renderer with a hosted backend or a secure, streaming preload and IPC bridge.
+platforms: ["react"]
+---
+
+assistant-ui works in Electron through `@assistant-ui/react`. The renderer is a React DOM environment, so there is no separate `@assistant-ui/electron` package to install. The Electron-specific decision is where model requests run and how the renderer reaches them.
+
+<Callout type="warn">
+  Never put a provider API key in renderer code, a `VITE_*` variable, or a preload script. Bundled values are readable by anyone with the app. Keep remote credentials on your backend, or keep local credentials in the main process and provision them with an OS-backed secret store.
+</Callout>
+
+## Choose a connection pattern
+
+| Pattern | Use it when | Runtime |
+| --- | --- | --- |
+| Hosted backend | You already have an AI SDK endpoint, need server auth or persistence, or ship the app to other people | `useChatRuntime` with an absolute HTTPS URL |
+| Local main process | The desktop app owns the provider or agent process and must work without your web backend | `useLocalRuntime` with a narrow preload/IPC bridge |
+
+```mermaid
+flowchart LR
+  Renderer["Electron renderer<br/>assistant-ui React"] -->|"absolute HTTPS"| Backend["Hosted chat backend"]
+  Renderer -->|"window.assistantAI"| Preload["context-isolated preload"]
+  Preload -->|"transferred MessagePort"| Main["Electron main process"]
+  Backend --> Provider["Model or agent"]
+  Main --> Provider
+```
+
+Do not send an SDK client, assistant-ui runtime, callback, `AbortSignal`, or `File` through IPC. Electron IPC uses structured clone semantics; define a small data-only protocol instead.
+
+## Pattern 1: hosted backend
+
+This is the smallest integration. Keep your existing AI SDK chat route and point `AssistantChatTransport` at its public URL.
+
+```tsx title="renderer/assistant-runtime.tsx"
+import type { ReactNode } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  AssistantChatTransport,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+
+const transport = new AssistantChatTransport({
+  api: "https://api.example.com/chat",
+});
+
+export function ElectronRuntimeProvider({ children }: { children: ReactNode }) {
+  const runtime = useChatRuntime({ transport });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+The URL must be absolute in a packaged app. A relative value such as `/api/chat` targets the renderer's `file://` or custom-protocol origin, not your deployed backend. Configure the backend's CORS policy for the packaged origin, allow the endpoint in `connect-src`, and authenticate requests as you would from any desktop client.
+
+The endpoint must return the AI SDK UI message stream consumed by `AssistantChatTransport`. See the [AI SDK runtime guide](/docs/runtimes/ai-sdk/v7) for the backend route and tool-calling setup.
+
+## Pattern 2: local main process
+
+Use this pattern when the Electron main process calls the model or runs a local agent. Keep `contextIsolation: true`, `sandbox: true`, and `nodeIntegration: false` on the `BrowserWindow`. Register `registerAssistantIpc(mainWindow)` after creating the trusted window.
+
+The following example is intentionally text-only. It streams one request over a dedicated `MessagePort`; closing that port propagates assistant-ui's Stop action to an `AbortController` in the main process.
+
+### 1. Define a data-only protocol
+
+Place the shared types somewhere all three Electron bundles can import.
+
+```ts title="shared/assistant-ipc.ts"
+export const ASSISTANT_STREAM_CHANNEL = "assistant:stream";
+
+export type ChatMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string };
+
+export type ChatRequest = {
+  system?: string;
+  messages: ChatMessage[];
+};
+
+export type ChatEvent =
+  | { type: "delta"; text: string }
+  | { type: "done" }
+  | { type: "error"; message: string };
+
+export type AssistantAI = {
+  streamChat(
+    request: ChatRequest,
+    onEvent: (event: ChatEvent) => void,
+  ): () => void;
+};
+```
+
+### 2. Expose one preload capability
+
+Expose the smallest API the renderer needs, not `ipcRenderer` itself. The callback receives only validated event data, never Electron's privileged IPC event object.
+
+```ts title="preload/assistant.ts"
+import { contextBridge, ipcRenderer } from "electron";
+import {
+  ASSISTANT_STREAM_CHANNEL,
+  type AssistantAI,
+  type ChatEvent,
+} from "./shared";
+
+const assistantAI: AssistantAI = {
+  streamChat(request, onEvent) {
+    const { port1, port2 } = new MessageChannel();
+    const onMessage = (event: MessageEvent<ChatEvent>) => onEvent(event.data);
+
+    port1.addEventListener("message", onMessage);
+    port1.start();
+    ipcRenderer.postMessage(ASSISTANT_STREAM_CHANNEL, request, [port2]);
+
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      port1.removeEventListener("message", onMessage);
+      port1.close();
+    };
+  },
+};
+
+contextBridge.exposeInMainWorld("assistantAI", assistantAI);
+```
+
+Declare the context-bridge API for renderer TypeScript:
+
+```ts title="renderer/electron.d.ts"
+import type { AssistantAI } from "./shared";
+
+declare global {
+  interface Window {
+    assistantAI: AssistantAI;
+  }
+}
+
+export {};
+```
+
+### 3. Stream from the main process
+
+Install the provider packages in the Electron main-process bundle:
+
+```sh
+pnpm add ai @ai-sdk/openai
+```
+
+The handler checks both the sending `WebContents` and its main frame, validates the untrusted payload and bounds its size before calling the model. Set `OPENAI_API_KEY` only in the main-process environment.
+
+```ts title="main/assistant-ipc.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+import { ipcMain, type BrowserWindow, type IpcMainEvent } from "electron";
+import {
+  ASSISTANT_STREAM_CHANNEL,
+  type ChatEvent,
+  type ChatRequest,
+} from "./shared";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isChatRequest = (value: unknown): value is ChatRequest => {
+  if (!isRecord(value) || !Array.isArray(value.messages)) return false;
+  if (value.system !== undefined && typeof value.system !== "string") {
+    return false;
+  }
+  if (value.messages.length > 200) return false;
+
+  let totalLength = typeof value.system === "string" ? value.system.length : 0;
+  for (const message of value.messages) {
+    if (!isRecord(message)) return false;
+    if (message.role !== "user" && message.role !== "assistant") return false;
+    if (typeof message.content !== "string") return false;
+    totalLength += message.content.length;
+    if (totalLength > 1_000_000) return false;
+  }
+
+  return true;
+};
+
+export function registerAssistantIpc(mainWindow: BrowserWindow) {
+  const handleStream = (event: IpcMainEvent, request: unknown) => {
+    const [port] = event.ports;
+    if (!port) return;
+
+    if (
+      event.sender !== mainWindow.webContents ||
+      event.senderFrame !== mainWindow.webContents.mainFrame
+    ) {
+      port.close();
+      return;
+    }
+
+    port.start();
+    if (!isChatRequest(request)) {
+      port.postMessage({
+        type: "error",
+        message: "Invalid chat request.",
+      } satisfies ChatEvent);
+      port.close();
+      return;
+    }
+
+    const abortController = new AbortController();
+    port.once("close", () => abortController.abort());
+    const send = (message: ChatEvent) => port.postMessage(message);
+
+    void (async () => {
+      try {
+        const result = streamText({
+          model: openai("gpt-5.4-mini"),
+          messages: request.messages,
+          ...(request.system ? { system: request.system } : {}),
+          abortSignal: abortController.signal,
+        });
+
+        for await (const text of result.textStream) {
+          send({ type: "delta", text });
+        }
+        send({ type: "done" });
+      } catch (error) {
+        if (abortController.signal.aborted) return;
+        console.error("Assistant stream failed", error);
+        send({ type: "error", message: "The model request failed." });
+      }
+    })();
+  };
+
+  ipcMain.on(ASSISTANT_STREAM_CHANNEL, handleStream);
+  mainWindow.once("closed", () => {
+    ipcMain.removeListener(ASSISTANT_STREAM_CHANNEL, handleStream);
+  });
+}
+```
+
+If your app can open more than one trusted assistant window, register a unique channel per window or route requests through one application-level registry. A global `ipcMain.on` listener should not be re-registered under the same channel for every window.
+
+### 4. Adapt IPC to assistant-ui
+
+`ChatModelAdapter` yields complete snapshots, so the renderer accumulates each IPC delta before yielding it. Its cleanup function closes the port on Stop, unmount, or completion.
+
+```tsx title="renderer/assistant-runtime.tsx"
+import type { ReactNode } from "react";
+import {
+  AssistantRuntimeProvider,
+  useLocalRuntime,
+  type ChatModelAdapter,
+} from "@assistant-ui/react";
+import type { ChatMessage } from "./shared";
+
+const ipcChatModel: ChatModelAdapter = {
+  async *run({ messages, context, abortSignal }) {
+    abortSignal.throwIfAborted();
+
+    const system = [context.system];
+    const serializedMessages: ChatMessage[] = [];
+
+    for (const message of messages) {
+      const text = message.content
+        .flatMap((part) => (part.type === "text" ? [part.text] : []))
+        .join("\n");
+      if (!text) continue;
+
+      if (message.role === "system") system.push(text);
+      if (message.role === "user") {
+        serializedMessages.push({ role: "user", content: text });
+      }
+      if (message.role === "assistant") {
+        serializedMessages.push({ role: "assistant", content: text });
+      }
+    }
+
+    const systemText = system.filter(Boolean).join("\n\n");
+    let stop: (() => void) | undefined;
+    let removeAbortListener: (() => void) | undefined;
+    const deltas = new ReadableStream<string>({
+      start(controller) {
+        let settled = false;
+        const close = () => {
+          if (settled) return;
+          settled = true;
+          controller.close();
+        };
+        const fail = (error: unknown) => {
+          if (settled) return;
+          settled = true;
+          controller.error(error);
+        };
+
+        stop = window.assistantAI.streamChat(
+          {
+            ...(systemText ? { system: systemText } : {}),
+            messages: serializedMessages,
+          },
+          (event) => {
+            if (event.type === "delta") controller.enqueue(event.text);
+            if (event.type === "done") close();
+            if (event.type === "error") fail(new Error(event.message));
+          },
+        );
+
+        const onAbort = () => {
+          stop?.();
+          fail(abortSignal.reason);
+        };
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+        removeAbortListener = () =>
+          abortSignal.removeEventListener("abort", onAbort);
+        if (abortSignal.aborted) onAbort();
+      },
+      cancel() {
+        stop?.();
+      },
+    });
+
+    const reader = deltas.getReader();
+    let fullText = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        fullText += value;
+        yield { content: [{ type: "text", text: fullText }] };
+      }
+    } finally {
+      removeAbortListener?.();
+      stop?.();
+      reader.releaseLock();
+    }
+  },
+};
+
+export function ElectronRuntimeProvider({ children }: { children: ReactNode }) {
+  const runtime = useLocalRuntime(ipcChatModel);
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+Wrap your existing assistant-ui thread with `ElectronRuntimeProvider`. Primitives and installed UI components work exactly as they do in a browser React app.
+
+## Extend the protocol deliberately
+
+The local example drops every non-text content part. Add explicit structured-clone-safe fields before claiming support for more features:
+
+- Attachments: pass bounded `ArrayBuffer` data or an app-owned file reference after validating type, size, and path in the main process. Do not pass browser `File` objects.
+- Tools: define serializable tool-call and tool-result events, and validate every tool invocation in the privileged process. Never expose a generic shell or filesystem IPC method.
+- Reasoning and metadata: add distinct event variants and map them to the corresponding assistant-ui content parts.
+- Thread persistence: store serializable thread data in the main process or use a remote thread-list adapter; do not try to transfer a runtime object.
+
+## Packaged-app checklist
+
+- Use an absolute HTTPS endpoint, a privileged custom protocol, or the preload bridge. Relative `/api/*` routes that worked against a development server will not follow your backend after packaging.
+- Serve local content through a custom protocol instead of `file://` when possible, and define a restrictive Content Security Policy. Do not disable `webSecurity` to work around origin errors.
+- Validate every IPC sender and every payload in the main process. Treat renderer data as untrusted even when the renderer is local.
+- Intercept new windows and external links with `webContents.setWindowOpenHandler`; do not let model-generated links create unrestricted Electron windows.
+- If you render remote HTML with `SafeContentFrame`, allow its documented host in `frame-src`. Ordinary text and Markdown rendering need no Electron-specific change.
+- Test the packaged build, not only the Vite or Webpack development server. The scheme, origin, preload path, CSP, and environment loading can all differ.
+
+For the underlying platform constraints, see Electron's official guides to [IPC and MessagePorts](https://www.electronjs.org/docs/latest/tutorial/message-ports), [context isolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation), and the [security checklist](https://www.electronjs.org/docs/latest/tutorial/security).

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

@@ -105,3 +105,13 @@ Alternative ways to connect a model.
     Run your app locally on a ChatGPT Plus or Pro plan via Codex OAuth, no API key required.
   </Card>
 </Cards>
+
+## Environments
+
+Run assistant-ui outside a conventional browser deployment.
+
+<Cards>
+  <Card title="Electron" href="/docs/guides/electron">
+    Connect an Electron renderer to a hosted backend or a secure, streaming preload/IPC bridge.
+  </Card>
+</Cards>

package/.docs/raw/docs/guides/quoting.mdx

@@ -127,7 +127,7 @@ function CustomQuoteDisplay() {
 
 ## Programmatic API
 
-Set or clear quotes via `useAui` from `@assistant-ui/react`. Call `aui.thread().composer().setQuote()` when your component is rendered outside of a specific thread context, or `aui.composer().setQuote()` when it is rendered inside a thread:
+Set or clear quotes via `useAui` from `@assistant-ui/react`. Call `aui.thread.composer().setQuote()` when your component is rendered outside of a specific thread context, or `aui.composer.setQuote()` when it is rendered inside a thread:
 
 ```tsx
 import { useAui } from "@assistant-ui/react";
@@ -136,14 +136,14 @@ function MyComponent() {
   const aui = useAui();
 
   const quoteText = () => {
-    aui.thread().composer().setQuote({
+    aui.thread.composer().setQuote({
       text: "The text to quote",
       messageId: "msg-123",
     });
   };
 
   const clearQuote = () => {
-    aui.thread().composer().setQuote(undefined);
+    aui.thread.composer().setQuote(undefined);
   };
 
   return (

package/.docs/raw/docs/guides/resumable-stream-deployment.mdx

@@ -143,7 +143,7 @@ Per-tenant prefixes also make incident response cheaper. A `SCAN MATCH aui:app:t
 
 ## Observability hooks
 
-`ResumableStreamContextOptions` exposes lifecycle hooks for structured logging, metrics, and tracing. Each hook is invoked synchronously around the underlying store call; throwing inside a hook surfaces as a producer error.
+`ResumableStreamContextOptions` exposes lifecycle hooks for structured logging, metrics, and tracing. Hook exceptions and rejected promises are reported through `console.error` without affecting stream output or stored lifecycle status.
 
 ```ts title="/lib/resumable-context.ts"
 import { createResumableStreamContext } from "assistant-stream/resumable";
@@ -170,7 +170,7 @@ export const resumableContext = createResumableStreamContext({
 });
 ```
 
-Keep hook bodies cheap. They run on the producer's hot path and any latency they add becomes streaming latency seen by the client.
+Keep synchronous hook work cheap. `onAcquire` runs on the `run()` request path for producers and consumers alike, while the remaining hooks run on the producer's streaming hot path. Returned promises are observed for failures but are not awaited.
 
 ## Resource limits
 

package/.docs/raw/docs/ink/hooks.mdx

@@ -41,11 +41,11 @@ import { useAui } from "@assistant-ui/react-ink";
 const aui = useAui();
 
 // Composer actions
-aui.composer().setText("Hello");
-aui.composer().send();
+aui.composer.setText("Hello");
+aui.composer.send();
 
 // Thread actions
-aui.thread().cancelRun();
+aui.thread.cancelRun();
 ```
 
 ### useAuiEvent

package/.docs/raw/docs/ink/primitives.mdx

@@ -396,7 +396,7 @@ Renders the quoted text from `s.composer.quote?.text`. Pass `children` to overri
 
 ### QuoteDismiss
 
-Pressable that clears the active quote by calling `aui.composer().setQuote(undefined)`.
+Pressable that clears the active quote by calling `aui.composer.setQuote(undefined)`.
 
 ```tsx
 <ComposerPrimitive.QuoteDismiss>
@@ -683,7 +683,7 @@ Container `Box` for an attachment. Forwards all `Box` props.
 
 ### Remove
 
-`Pressable` that calls `aui.attachment().remove()` when activated (Enter while focused). Disabled when not focused or when the `disabled` prop is set.
+`Pressable` that calls `aui.attachment.remove()` when activated (Enter while focused). Disabled when not focused or when the `disabled` prop is set.
 
 | Prop | Type | Description |
 |------|------|-------------|
@@ -725,7 +725,7 @@ Renders the queue item's prompt with Ink `<Text>`. Pass `children` to override t
 
 ### Remove
 
-Pressable that removes the queue item by calling `aui.queueItem().remove()`.
+Pressable that removes the queue item by calling `aui.queueItem.remove()`.
 
 ```tsx
 <QueueItemPrimitive.Remove>
@@ -742,7 +742,7 @@ Remaining props are forwarded to the underlying `Pressable` (Ink `Box` props).
 
 ### Steer
 
-Pressable that promotes the queue item to run next by calling `aui.queueItem().steer()`.
+Pressable that promotes the queue item to run next by calling `aui.queueItem.steer()`.
 
 ```tsx
 <QueueItemPrimitive.Steer>
@@ -765,10 +765,17 @@ import { ActionBarPrimitive } from "@assistant-ui/react-ink";
 
 ### Copy
 
-Pressable that copies the message content. Supports function-as-children for copy state feedback.
+Pressable that copies the message content. Pass a platform clipboard writer through `copyToClipboard`. Supports function-as-children for copy state feedback.
+
+<InstallCommand npm={["clipboardy"]} />
 
 ```tsx
-<ActionBarPrimitive.Copy copiedDuration={3000}>
+import clipboard from "clipboardy";
+
+<ActionBarPrimitive.Copy
+  copiedDuration={3000}
+  copyToClipboard={clipboard.write}
+>
   {({ isCopied }) => <Text>{isCopied ? "[Copied!]" : "[Copy]"}</Text>}
 </ActionBarPrimitive.Copy>
 ```
@@ -776,7 +783,7 @@ Pressable that copies the message content. Supports function-as-children for cop
 | Prop | Type | Description |
 |------|------|-------------|
 | `copiedDuration` | `number` | Duration in ms to show "copied" state (default: 3000) |
-| `copyToClipboard` | `(text: string) => void` | Custom clipboard function |
+| `copyToClipboard` | `(text: string) => void \| Promise<void>` | Platform clipboard writer |
 
 ### Edit
 

package/.docs/raw/docs/integrations/auth/better-auth.mdx

@@ -22,7 +22,7 @@ Three integration points:
 
 1. **Auth handlers** mounted at `/api/auth/[...all]/route.ts` via `toNextJsHandler(auth)`.
 2. **API routes** read the session server-side with `auth.api.getSession({ headers: await headers() })`.
-3. **Reload-on-auth** uses better-auth's React client to detect sign-in and trigger `aui.threads().reload()`.
+3. **Reload-on-auth** uses better-auth's React client to detect sign-in and trigger `aui.threads.reload()`.
 
 `session.user.id` is exposed on the session object directly, so route handlers can scope queries against it.
 
@@ -136,7 +136,7 @@ export function ReloadOnAuth() {
   const aui = useAui();
   const { data: session, isPending } = authClient.useSession();
   useEffect(() => {
-    if (!isPending && session) aui.threads().reload();
+    if (!isPending && session) aui.threads.reload();
   }, [isPending, session?.user?.id]);
   return null;
 }

package/.docs/raw/docs/integrations/auth/clerk.mdx

@@ -102,7 +102,7 @@ const rows = await db
 
 ### Reload threads after async auth
 
-The first render of `<MyProvider>` may run before Clerk resolves the user on the client. Drop a small effect inside `<AssistantRuntimeProvider>` that calls `aui.threads().reload()` once the user is loaded:
+The first render of `<MyProvider>` may run before Clerk resolves the user on the client. Drop a small effect inside `<AssistantRuntimeProvider>` that calls `aui.threads.reload()` once the user is loaded:
 
 ```tsx title="app/components/ReloadOnAuth.tsx"
 "use client";
@@ -115,7 +115,7 @@ export function ReloadOnAuth() {
   const aui = useAui();
   const { isLoaded, isSignedIn, user } = useUser();
   useEffect(() => {
-    if (isLoaded && isSignedIn) aui.threads().reload();
+    if (isLoaded && isSignedIn) aui.threads.reload();
   }, [isLoaded, isSignedIn, user?.id]);
   return null;
 }

package/.docs/raw/docs/integrations/auth/next-auth.mdx

@@ -18,7 +18,7 @@ Three places auth touches the integration:
 
 1. **API routes** (`/api/chat`, `/api/threads/*`) call `auth()` server-side, return 401 if no session, then scope DB queries by `session.user.id`.
 2. **`RemoteThreadListAdapter`** does nothing auth-specific; the cookie travels with the `fetch` calls automatically (same origin).
-3. **Reload-on-auth**: if the session resolves after the initial render, call `aui.threads().reload()` so the list re-fetches with the new identity.
+3. **Reload-on-auth**: if the session resolves after the initial render, call `aui.threads.reload()` so the list re-fetches with the new identity.
 
 ## Setup
 
@@ -113,7 +113,7 @@ Apply the same pattern to `POST`, `PATCH`, and `DELETE` handlers. Always verify
 
 ### Reload threads after async auth
 
-The first render of `<MyProvider>` may run before `auth()` resolves on the client. The thread list will be empty until the user refreshes. Drop a small effect into the layout to call `aui.threads().reload()` once the session resolves.
+The first render of `<MyProvider>` may run before `auth()` resolves on the client. The thread list will be empty until the user refreshes. Drop a small effect into the layout to call `aui.threads.reload()` once the session resolves.
 
 `useSession` requires `<SessionProvider>` higher in the tree. Wrap your root layout's client subtree once:
 
@@ -140,7 +140,7 @@ export function ReloadOnAuth() {
   const aui = useAui();
   const { status, data } = useSession();
   useEffect(() => {
-    if (status === "authenticated") aui.threads().reload();
+    if (status === "authenticated") aui.threads.reload();
   }, [status, data?.user?.id]);
   return null;
 }

package/.docs/raw/docs/integrations/observability/langsmith.mdx

@@ -35,7 +35,7 @@ LANGSMITH_API_KEY=lsv2_pt_...
 LANGSMITH_PROJECT=assistant-ui
 ```
 
-`LANGSMITH_PROJECT` controls which project receives traces; the default project applies if you omit it. See LangSmith's [environment variable reference](https://docs.langchain.com/langsmith/how_to_environment_variables) for the full list.
+`LANGSMITH_PROJECT` controls which project receives traces; the default project applies if you omit it. See LangSmith's [project configuration guide](https://docs.langchain.com/langsmith/log-traces-to-project) for details.
 
 </Step>
 <Step>