@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

package/.docs/raw/docs/runtimes/concepts/adapters.mdx

@@ -0,0 +1,265 @@
+---
+title: Adapters
+description: Reusable extension points for attachments, speech, feedback, history, and suggestions.
+---
+
+Adapters are how assistant-ui adds capabilities like file uploads or message persistence to a runtime without coupling the runtime to a specific backend. You implement a small interface, plug it into the runtime's `adapters` option, and the matching UI surfaces (paperclip button, audio button, history reload) light up.
+
+Every adapter on this page works the same way regardless of which runtime you use. When an adapter is supported by a runtime, you provide it via that runtime's `adapters` option:
+
+```ts
+const runtime = useLocalRuntime(modelAdapter, {
+  adapters: { attachments, history, speech, feedback, suggestion },
+});
+```
+
+Framework adapters take the same shape:
+
+```ts
+const runtime = useChatRuntime({ adapters: { attachments, history } });
+```
+
+## Support matrix
+
+| Adapter | LocalRuntime | ExternalStoreRuntime | DataStream | AssistantTransport | react-ai-sdk | react-langgraph | react-langchain | react-google-adk | react-a2a | react-ag-ui | react-opencode |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Attachments | Yes | Yes | Yes | Yes | Yes | (via thread state) | (via thread state) | Yes | Yes | Yes | (no) |
+| Speech | Yes | Yes | Yes | (no) | Yes | Yes | Yes | Yes | Yes | Yes | (no) |
+| Dictation | Yes | Yes | Yes | (no) | Yes | Yes | (no) | Yes | (no) | Yes | (no) |
+| Feedback | Yes | Yes | Yes | (no) | Yes | Yes | Yes | Yes | Yes | Yes | (no) |
+| History | Yes | (use your store) | Yes | (use thread converter) | Yes | (via load) | (via load) | Yes | Yes | Yes | (server-managed) |
+| Suggestion | Yes | (no) | Yes | (no) | (no) | (no) | (no) | (no) | (no) | (no) | (no) |
+| threadList | Yes (`RemoteThreadListAdapter`) | Yes (`ExternalStoreThreadListAdapter`) | Yes (`RemoteThreadListAdapter`) | Yes | Yes | Yes | Yes | Yes | Yes | Yes (experimental) | Built-in (sessions) |
+
+`(no)` means the adapter slot is not exposed by that runtime today. You would need to drop down a layer to use it.
+
+## Attachment adapter
+
+Handles file and image uploads. When present, the composer renders a paperclip button.
+
+```ts
+type AttachmentAdapter = {
+  accept: string;
+  add: (input: { file: File }) => Promise<PendingAttachment>;
+  send: (attachment: PendingAttachment) => Promise<CompleteAttachment>;
+  remove?: (attachment: Attachment) => Promise<void>;
+};
+```
+
+Three lifecycle methods:
+
+- `add` runs when the user picks a file. Upload it, return a record with status `requires-action` so the composer holds the file before sending.
+- `send` runs when the user submits the message. Finalize the upload, attach a `content` payload, and mark status `complete`.
+- `remove` is optional and runs when the user removes the attachment before sending.
+
+Minimal upload-and-send example:
+
+```ts
+const attachmentAdapter: AttachmentAdapter = {
+  accept: "image/*,application/pdf",
+  async add({ file }) {
+    const form = new FormData();
+    form.append("file", file);
+    const { id, url } = await fetch("/api/upload", {
+      method: "POST",
+      body: form,
+    }).then((r) => r.json());
+    return {
+      id,
+      type: file.type.startsWith("image/") ? "image" : "document",
+      name: file.name,
+      contentType: file.type,
+      file,
+      url,
+      status: { type: "requires-action", reason: "composer-send" },
+    };
+  },
+  async send(attachment) {
+    return {
+      ...attachment,
+      status: { type: "complete" },
+      content: [
+        attachment.type === "image"
+          ? { type: "image", image: attachment.url! }
+          : { type: "text", text: `[${attachment.name}](${attachment.url})` },
+      ],
+    };
+  },
+};
+```
+
+For multiple file types use `CompositeAttachmentAdapter`:
+
+```ts
+import {
+  CompositeAttachmentAdapter,
+  SimpleImageAttachmentAdapter,
+  SimpleTextAttachmentAdapter,
+} from "@assistant-ui/react";
+
+const attachmentAdapter = new CompositeAttachmentAdapter([
+  new SimpleImageAttachmentAdapter(),
+  new SimpleTextAttachmentAdapter(),
+]);
+```
+
+## Speech adapter
+
+Text-to-speech for assistant messages. When present, message bubbles render an audio button.
+
+```ts
+type SpeechSynthesisAdapter = {
+  speak: (text: string) => Utterance;
+};
+```
+
+`speak` returns an `Utterance` with `cancel()`, a `status` field, and `subscribe(callback)`. Browser-native example:
+
+```ts
+const speechAdapter: SpeechSynthesisAdapter = {
+  speak(text) {
+    const utterance = new SpeechSynthesisUtterance(text);
+    const subscribers = new Set<() => void>();
+    const result: SpeechSynthesisAdapter.Utterance = {
+      status: { type: "running" },
+      cancel: () => {
+        speechSynthesis.cancel();
+        result.status = { type: "ended", reason: "cancelled" };
+        subscribers.forEach((cb) => cb());
+      },
+      subscribe(cb) {
+        subscribers.add(cb);
+        return () => subscribers.delete(cb);
+      },
+    };
+    utterance.addEventListener("end", () => {
+      result.status = { type: "ended", reason: "finished" };
+      subscribers.forEach((cb) => cb());
+    });
+    speechSynthesis.speak(utterance);
+    return result;
+  },
+};
+```
+
+## Dictation adapter
+
+Speech-to-text input for the composer. When present, the composer renders a microphone button. The contract is parallel to the speech adapter.
+
+## Feedback adapter
+
+Thumbs up / thumbs down on assistant messages. When present, message bubbles render feedback buttons.
+
+```ts
+type FeedbackAdapter = {
+  submit: (feedback: {
+    type: "positive" | "negative";
+    message: ThreadMessage;
+  }) => Promise<void>;
+};
+```
+
+```ts
+const feedbackAdapter: FeedbackAdapter = {
+  async submit({ type, message }) {
+    await fetch("/api/feedback", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ messageId: message.id, rating: type }),
+    });
+  },
+};
+```
+
+## History adapter
+
+Per-thread message persistence. Used by `LocalRuntime` and adapters built on it (`react-ai-sdk`, `react-google-adk`, `react-a2a`, `useDataStreamRuntime`).
+
+`ExternalStoreRuntime` does not use a history adapter directly, since you already own the message array. Persist via your store instead. `react-langgraph` and `react-langchain` source persistence from server-side thread state, exposed through their `load` callbacks.
+
+```ts
+type ThreadHistoryAdapter = {
+  load: () => Promise<{
+    messages: { parentId: string | null; message: ThreadMessage }[];
+  }>;
+  append: (item: {
+    parentId: string | null;
+    message: ThreadMessage;
+  }) => Promise<void>;
+  resume?: (input: {
+    messages: ThreadMessage[];
+  }) => Promise<ReadableStream | undefined>;
+  withFormat?: <Fmt>(fmt: Fmt) => ThreadHistoryAdapter;
+};
+```
+
+`load` runs when a thread opens. `append` runs after each message completes.
+
+<Callout type="info">
+`react-ai-sdk` requires `withFormat` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime in the AI SDK path. See the [AI SDK history docs](/docs/runtimes/ai-sdk/v6) for the full pattern.
+</Callout>
+
+## Suggestion adapter
+
+Proposes follow-up prompts after each assistant message. When present, suggestion chips render under the latest assistant message.
+
+```ts
+type SuggestionAdapter = {
+  generate: (input: {
+    messages: readonly ThreadMessage[];
+  }) => AsyncGenerator<{ prompt: string }[]>;
+};
+```
+
+```ts
+const suggestionAdapter: SuggestionAdapter = {
+  async *generate({ messages }) {
+    const last = messages.at(-1);
+    if (!last) return;
+    const response = await fetch("/api/suggestions", {
+      method: "POST",
+      body: JSON.stringify(last),
+    });
+    yield (await response.json()).suggestions;
+  },
+};
+```
+
+## Thread list adapter
+
+Multi-thread support is documented separately, since the contract differs by runtime. See [threads](/docs/runtimes/concepts/threads).
+
+## Composing adapters
+
+Adapters compose freely. Provide as many or as few as you need; UI surfaces enable based on which slots are filled.
+
+```ts
+const runtime = useLocalRuntime(modelAdapter, {
+  adapters: {
+    attachments: myAttachmentAdapter,
+    history: myHistoryAdapter,
+    speech: mySpeechAdapter,
+    feedback: myFeedbackAdapter,
+  },
+});
+```
+
+## Related
+
+<Cards>
+  <Card
+    title="Threads"
+    description="Multi-thread support: cloud, custom database, ExternalStore."
+    href="/docs/runtimes/concepts/threads"
+  />
+  <Card
+    title="Architecture"
+    description="The three-layer runtime model and how adapters fit in."
+    href="/docs/runtimes/concepts/architecture"
+  />
+  <Card
+    title="Pick a runtime"
+    description="Choose the right runtime for your backend."
+    href="/docs/runtimes/pick-a-runtime"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/concepts/architecture.mdx

@@ -0,0 +1,125 @@
+---
+title: Runtime architecture
+description: How core runtimes, protocol layers, and framework adapters fit together.
+---
+
+assistant-ui exposes runtime integrations at three layers. Understanding which layer you are picking from clarifies what each runtime gives you and how features flow between them.
+
+## The three layers
+
+```mermaid
+graph TD
+    subgraph Framework["Framework adapters"]
+      A1[react-ai-sdk]
+      A2[react-langgraph]
+      A3[react-langchain]
+      A4[react-google-adk]
+      A5[react-a2a]
+      A6[react-ag-ui]
+      A7[react-opencode]
+    end
+    subgraph Protocol["Protocol layers"]
+      P1[DataStream]
+      P2[AssistantTransport]
+    end
+    subgraph Core["Core runtimes"]
+      C1[LocalRuntime]
+      C2[ExternalStoreRuntime]
+    end
+    A1 --> C2
+    A2 --> C2
+    A3 --> C2
+    A4 --> C2
+    A5 --> C2
+    A6 --> C2
+    A7 --> C2
+    P1 --> C1
+    P2 --> C2
+```
+
+Each upper layer is implemented in terms of a lower one. You can drop down a layer whenever you need more control, but most users start at the framework layer and never touch the others.
+
+## Core runtimes
+
+These own everything assistant-ui considers a runtime: messages, threads, branching, edit and regenerate state, run lifecycle. Every other layer is built on one of them.
+
+**`LocalRuntime`** keeps state inside the runtime itself and exposes a `ChatModelAdapter` interface. You implement a single `run` function (or `async *run` for streaming) and the runtime takes care of branching, editing, regeneration, and history through built-in plumbing.
+
+**`ExternalStoreRuntime`** is the inverse: you own the message array and provide callbacks (`onNew`, `onEdit`, `onReload`, etc.). The runtime renders whatever you give it. UI features turn on based on which callbacks are present.
+
+| Concern | LocalRuntime | ExternalStoreRuntime |
+| --- | --- | --- |
+| State ownership | Runtime | You |
+| Setup complexity | Low | Medium |
+| Branching | Built in | Requires `setMessages` |
+| Editing | Built in | Requires `onEdit` |
+| Best fit | Greenfield projects | Redux, zustand, tanstack-query stacks |
+
+See [LocalRuntime](/docs/runtimes/custom/local-runtime) and [ExternalStoreRuntime](/docs/runtimes/custom/external-store) for full guides.
+
+## Protocol layers
+
+These wrap a core runtime with a wire-protocol contract so a generic backend can talk to assistant-ui without writing a custom `ChatModelAdapter` each time.
+
+**`DataStream`** is a message-streaming protocol. Your backend emits a standardized stream of message parts (text deltas, tool calls) and `useDataStreamRuntime` consumes it on top of `LocalRuntime`. Closest to "AI SDK style streaming for any backend".
+
+**`AssistantTransport`** is a state-streaming protocol. Your backend sends snapshots of its agent state and the runtime converts them into UI messages on top of `ExternalStoreRuntime`. Closest to "stream the whole agent state, not just messages".
+
+| Protocol | Layered on | Choose when |
+| --- | --- | --- |
+| DataStream | LocalRuntime | Your backend already speaks the data stream protocol, or you want a thin message-stream contract |
+| AssistantTransport | ExternalStoreRuntime | Your agent has internal state worth surfacing, or you need bidirectional commands and custom command types |
+
+## Framework adapters
+
+The fastest path. Each adapter wraps one of the core or protocol layers and adds framework-specific conveniences.
+
+| Adapter | Layered on | Targets |
+| --- | --- | --- |
+| `react-ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v6 (`useChat`) |
+| `react-langgraph` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/langgraph-sdk` |
+| `react-langchain` | `ExternalStoreRuntime` | LangGraph Cloud via `@langchain/react`'s `useStream` |
+| `react-google-adk` | `ExternalStoreRuntime` | Google ADK JS or Python agents |
+| `react-a2a` | `ExternalStoreRuntime` | Any A2A v1.0 protocol server |
+| `react-ag-ui` | `ExternalStoreRuntime` | AG-UI protocol agents (CopilotKit, custom servers) |
+| `react-opencode` | `ExternalStoreRuntime` | OpenCode coding-agent server (experimental) |
+
+When an adapter exposes a feature like attachments, speech, or feedback, it does so through the same [adapter interfaces](/docs/runtimes/concepts/adapters) the core runtimes use. A feature implemented once works the same way across runtimes.
+
+## How features flow
+
+A few things follow predictable patterns regardless of layer:
+
+- **Adapters** (attachments, speech, feedback, history, suggestions) are configured the same way and carry the same contract everywhere. See [adapters](/docs/runtimes/concepts/adapters).
+- **Threads** (single, cloud, custom database) work via a shared `RemoteThreadListAdapter` for `LocalRuntime`-based runtimes and a separate `ExternalStoreThreadListAdapter` for `ExternalStoreRuntime`. See [threads](/docs/runtimes/concepts/threads).
+- **Unstable APIs** are surfaced with an `unstable_` prefix and may change in any release. See [stability](/docs/runtimes/concepts/stability).
+
+## Choosing a layer
+
+Start at the top, descend only when blocked.
+
+1. **Framework adapter** if your backend matches one. You get streaming, threads, and adapter slots without writing protocol code.
+2. **Protocol layer** if no framework adapter fits but you can pick a wire format. `DataStream` for message streaming, `AssistantTransport` for state streaming.
+3. **Core runtime** if your situation is too custom for a protocol. `LocalRuntime` for simple cases, `ExternalStoreRuntime` if you already have a store.
+
+If you are unsure, start at [picking a runtime](/docs/runtimes/pick-a-runtime).
+
+## Related
+
+<Cards>
+  <Card
+    title="Adapters"
+    description="Attachments, speech, feedback, history, suggestions across runtimes."
+    href="/docs/runtimes/concepts/adapters"
+  />
+  <Card
+    title="Threads"
+    description="Multi-thread support: cloud, custom database, ExternalStore."
+    href="/docs/runtimes/concepts/threads"
+  />
+  <Card
+    title="Stability"
+    description="What unstable_ means and which APIs may change."
+    href="/docs/runtimes/concepts/stability"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/concepts/stability.mdx

@@ -0,0 +1,67 @@
+---
+title: Stability
+description: What unstable_ means, when APIs become stable, and how to track changes.
+---
+
+assistant-ui ships some APIs with an `unstable_` prefix. This is a deliberate signal, not a bug.
+
+## What `unstable_` means
+
+An `unstable_` prefix tells you that the API is exposed publicly so you can build against it, but the surface (signature, naming, semantics, return shape) may change in any release including patch releases.
+
+If you depend on an unstable API:
+
+- **Pin your dependency range** so an automatic minor or patch update cannot rewrite the contract under you.
+- **Isolate the call site** behind a small wrapper in your code so you can adapt to upstream changes in one place.
+- **Expect renames or removals** when the API stabilizes; the prefix gets dropped on the stable form.
+
+## Why we ship them
+
+Three reasons something stays `unstable_`:
+
+1. **The design is still in flux** and we want feedback on the current shape before committing.
+2. **The API depends on internals** we are still rearranging, so the surface tracks that motion.
+3. **The use case is real today** but stable-api expectations (semver discipline, comprehensive coverage, docs) have not been met yet.
+
+## Currently unstable APIs
+
+A non-exhaustive list of `unstable_` exports surfaced in the runtime docs.
+
+| API | Package | Notes |
+| --- | --- | --- |
+| `unstable_createMessageConverter` | `@assistant-ui/react` | Message-format converter used by AssistantTransport and DataStream. |
+| `unstable_humanToolNames` | `@assistant-ui/react` | Tool names that pause for human approval. Only available on LocalRuntime; not supported in DataStream. |
+| `unstable_threadListAdapter` | `@assistant-ui/react-langgraph` | LangGraph thread-list adapter slot on `useLangGraphRuntime`. |
+| `unstable_createLangGraphStream` | `@assistant-ui/react-langgraph` | End-to-end cancellation primitive. |
+| `unstable_Provider` | Various adapters | Thread-scoped provider on `RemoteThreadListAdapter`. Must render children synchronously. |
+| `unstable_capabilities` | `ExternalStoreRuntime` | Toggle copy and other thread capabilities. |
+| `unstable_state`, `unstable_annotations`, `unstable_data` | Message metadata | Runtime-internal fields exposed for advanced use cases. |
+| `unstable_assistantMessageId`, `unstable_threadId`, `unstable_parentId`, `unstable_getMessage` | `ChatModelRunOptions` | Identifiers and accessors passed to your `ChatModelAdapter.run`. |
+
+Framework adapters list their own unstable surface in the corresponding adapter pages.
+
+## When something stabilizes
+
+Stabilization usually drops the prefix. If `unstable_foo` becomes stable, the new export is `foo`, the old name is kept as a deprecated alias for at least one minor cycle, and the changelog calls out the change.
+
+Watch the [release notes](https://github.com/assistant-ui/assistant-ui/releases) and the [migration guides](/docs/migrations) for transitions.
+
+## Related
+
+<Cards>
+  <Card
+    title="Architecture"
+    description="The three-layer runtime model."
+    href="/docs/runtimes/concepts/architecture"
+  />
+  <Card
+    title="Adapters"
+    description="The shared adapter contracts."
+    href="/docs/runtimes/concepts/adapters"
+  />
+  <Card
+    title="Threads"
+    description="Multi-thread support patterns."
+    href="/docs/runtimes/concepts/threads"
+  />
+</Cards>