@assistant-ui/mcp-docs-server 0.2.3 → 0.3.1

package/.docs/raw/docs/runtimes/claude-managed-agents.mdx

@@ -1,118 +0,0 @@
----
-title: Claude Managed Agents
-description: Connect Anthropic's Managed Agents sessions to assistant-ui with the external store runtime, folding the session event log into messages, rendering approval gates, and using sessions as the thread list.
----
-
-[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) is Anthropic's hosted agent platform: Anthropic runs the agent loop and provisions a sandboxed container per session, and your client drives the session over an event stream. A session holds the entire conversation server-side as a durable event log, streams every step (text, tool calls, approval stops, status) as typed events, and accepts user messages and tool confirmations back.
-
-That shape maps directly onto two assistant-ui primitives, with no adapter package in between:
-
-- [`useExternalStoreRuntime`](/docs/runtimes/custom/external-store) renders messages you derive from the session's event log. The log is the single source of truth, so replaying a stored session and tailing a live one run through the same pure function and can never disagree.
-- [`useRemoteThreadListRuntime`](/docs/api-reference/hooks/runtimes#useremotethreadlistruntime) turns the session list into the thread sidebar. A thread is a session; there is no conversations table anywhere in the app.
-
-Anthropic ships an official reference implementation of this integration: the [Claude Managed Agents quickstart](https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/assistant-ui) is a complete Next.js app (composer, thread, sidebar, tool cards, approval gate) built exactly this way. This page teaches the pattern; the quickstart is the runnable proof.
-
-<Callout type="info">
-Managed Agents is a beta API (`managed-agents-2026-04-01`; the SDK sets the header automatically). The quickstart declares `@anthropic-ai/sdk` `^0.113.0` (the session event helpers and token previews need 0.109.0 or later), and `@assistant-ui/react` 0.14.27 or later for the toolkit API and the approval gate on the external store runtime.
-</Callout>
-
-## The event-to-message mapping
-
-Everything the session emits arrives as a typed event. The integration is one pure fold from the event array to assistant-ui's message model:
-
-| Managed Agents event | assistant-ui |
-| --- | --- |
-| `user.message` | A user message |
-| `agent.message` | Assistant text (buffered, authoritative) |
-| `event_start` / `event_delta` | The same text, streamed early as token previews |
-| `agent.thinking` | A reasoning part (progress signal only; the API sends no reasoning text) |
-| `agent.tool_use` / `agent.mcp_tool_use` / `agent.custom_tool_use` | A tool-call part; the `toolCallId` is the event id |
-| `agent.tool_result` (and mcp / custom variants) | That part's result |
-| `session.status_idle` with `stop_reason: requires_action` | `requires-action` message status, plus an approval on each blocked tool part |
-| `user.tool_confirmation` | The approval, settled (allowed or denied) |
-| `session.status_running` / `status_idle` | Whether the turn is live (`isRunning`) |
-| `session.error` | An error status on the message, or a retry banner |
-
-Because the fold is pure, opening an old chat replays `sessions.events.list()` through it, and a live chat feeds the SSE tail through it, and the two paths cannot render differently. Approvals, denials, and charts all come back after a reload because they are in the log, not in browser state.
-
-The runtime wiring is a structural subset of `ThreadMessageLike`, handed to the external store as-is:
-
-```tsx
-const runtime = useExternalStoreRuntime<ThreadMessageLike>({
-  messages: snapshot.messages,
-  convertMessage: (m) => m,
-  isRunning: isBusy(snapshot),
-
-  onNew: async (message) => {
-    const id = await ensureSession();
-    await sendMessage(id, textOf(message));
-  },
-
-  // The Stop button becomes a real server-side interrupt.
-  onCancel: async () => controller.interrupt(),
-
-  // The Allow / Deny click on a gated tool call. approvalId is the
-  // tool_use event id from session.status_idle { requires_action }.
-  onRespondToToolApproval: async ({ approvalId, approved, reason }) => {
-    controller.respondToApproval(approvalId, approved, reason);
-  },
-});
-```
-
-## Sessions are the thread list
-
-The sidebar is a `RemoteThreadListAdapter` over the Managed Agents session API. Thread id and session id are the same string, so nothing maps between the two worlds:
-
-| Adapter method | Managed Agents call |
-| --- | --- |
-| `list` | `sessions.list()`, filtered to the sessions this app created (a `metadata` tag) |
-| `initialize` | `sessions.create()`, invoked by assistant-ui on the first message of a new chat |
-| `rename` | `sessions.update({ title })` |
-| `archive` | `sessions.archive()` |
-| `unarchive` | Throws. Managed Agents sessions cannot be unarchived, and switching to an archived thread auto-unarchives by default, so do not render archived sessions as switchable (the quickstart's ownership gate rejects archived ids outright) |
-| `delete` | `sessions.delete()` |
-| `fetch` | `sessions.retrieve()` |
-| `generateTitle` | Reads the title back after the server retitles the session from the first message, so the sidebar row updates without a second model call |
-
-A brand-new chat has no session until the first send: the composer works immediately, and `initialize()` creates the session lazily when the first message (or first attachment upload) needs one. Kill the server, restart, reload, and every conversation comes back, because none of it ever lived in the app.
-
-## The approval gate
-
-Managed Agents supports per-tool [permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies). A tool configured as `always_ask` (the quickstart gates `bash` this way) does not run when the agent reaches for it. The session emits the `agent.tool_use` event, then parks:
-
-```json
-{ "type": "session.status_idle", "stop_reason": { "type": "requires_action", "event_ids": ["sevt_..."] } }
-```
-
-The fold stamps an approval onto that tool part and sets the message status to `requires-action`, which is everything assistant-ui needs to render Allow and Deny on the tool card. The click flows back through `onRespondToToolApproval` as a `user.tool_confirmation` event:
-
-```json
-{ "type": "user.tool_confirmation", "tool_use_id": "sevt_...", "result": "deny", "deny_message": "Not on this box." }
-```
-
-Two wire details matter. The `tool_use_id` is the tool-use event id, not an Anthropic `toolu_` id. And a denial reaches the agent as the tool's result, so it adjusts course instead of retrying the same command.
-
-Custom client-executed tools ride the same `requires_action` stop but take a `user.custom_tool_result` instead of a confirmation; sending a confirmation for one is a 400. The quickstart's inline chart tool is the worked example: the session parks, the card renders the chart from the tool's input, and the client answers so the agent continues.
-
-## Token streaming
-
-By default assistant text arrives as whole `agent.message` events when a model request finishes. Opting the stream into `event_deltas: ["agent.message", "agent.thinking"]` adds token previews: an `event_start` announces the upcoming event, `event_delta` fragments stream the text, and the buffered event lands last as the authoritative record. Concatenating a preview's deltas in arrival order yields a prefix of the final text, but under load the server may shed the remaining deltas for an event, so the prefix is not necessarily the whole message. The fold therefore appends fragments for display and discards the accumulated preview when the buffered event arrives; never treat a preview as final. When a turn errors or is interrupted, the buffered event may never arrive at all, but `span.model_request_end` still does, so close any unreconciled preview when you see it.
-
-Previews are best-effort and gated per organization. Build against the buffered events and treat deltas as an enhancement: an org without the streaming gate runs the identical code path with replies arriving whole.
-
-## Security boundary
-
-The Anthropic API key stays server-side; the browser talks only to your own route handlers, which relay to Managed Agents. Because a session id arrives from the browser and becomes an API path parameter, validate ownership on every route: the id must resolve, belong to your agent, and carry your app's metadata tag before any read or write. The API key can see the whole workspace; that gate is what keeps a guessed id from reading it. The quickstart's [`ownedSession()`](https://github.com/anthropics/claude-quickstarts/blob/main/managed-agents/assistant-ui/lib/owned-session.ts) is the reference shape.
-
-## Run the reference
-
-```bash
-git clone https://github.com/anthropics/claude-quickstarts
-cd claude-quickstarts/managed-agents/assistant-ui
-npm install
-cp .env.example .env   # add ANTHROPIC_API_KEY, or `ant auth login` once
-npm run setup          # one-time: creates the agent + environment, paste the IDs into .env
-npm run dev            # drop sample_data/sales.csv into the chat
-```
-
-The quickstart's [README](https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/assistant-ui#readme) walks through every file: the reducer, the session controller, the thread list adapter, the tool cards, and the attachment adapter that uploads composer files into the session sandbox. For the platform itself, start with Anthropic's [Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview) and [events reference](https://platform.claude.com/docs/en/managed-agents/events-and-streaming).

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

@@ -1,265 +0,0 @@
----
-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 | 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 (`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">
-`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/v7) 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

@@ -1,167 +0,0 @@
----
-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
-
-<Flow.Root
-  llm={`graph TD
-    subgraph Framework["Framework adapters"]
-      A1[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`}
->
-  <Flow.Canvas
-    edges={[
-      { from: "datastream", to: "local", route: "down", midFrac: 0.4, laneOffset: -60 },
-      { from: "transport", to: "external", route: "down", midFrac: 0.65, toOffset: -14 },
-      { from: "adapters", to: "external", route: "down", midFrac: 0.4, toOffset: 14 },
-    ]}
-  >
-    <div className="grid max-w-2xl grid-cols-[1fr_1.6fr] gap-4">
-      <Flow.Group>
-        <Flow.GroupLabel>Protocol layers</Flow.GroupLabel>
-        <Flow.Column className="items-stretch gap-5">
-          <Flow.Row className="justify-start">
-            <Flow.Node flowId="datastream">DataStream</Flow.Node>
-          </Flow.Row>
-          <Flow.Row className="justify-end">
-            <Flow.Node flowId="transport">AssistantTransport</Flow.Node>
-          </Flow.Row>
-        </Flow.Column>
-      </Flow.Group>
-      <Flow.Group flowId="adapters">
-        <Flow.GroupLabel>Framework adapters</Flow.GroupLabel>
-        <Flow.Row className="flex-wrap justify-start">
-          <Flow.Node>ai-sdk</Flow.Node>
-          <Flow.Node>react-langgraph</Flow.Node>
-          <Flow.Node>react-langchain</Flow.Node>
-          <Flow.Node>react-google-adk</Flow.Node>
-          <Flow.Node>react-a2a</Flow.Node>
-          <Flow.Node>react-ag-ui</Flow.Node>
-          <Flow.Node>react-opencode</Flow.Node>
-        </Flow.Row>
-      </Flow.Group>
-    </div>
-    <div className="h-14" aria-hidden />
-    <Flow.Group className="mx-auto w-fit">
-      <Flow.GroupLabel>Core runtimes</Flow.GroupLabel>
-      <Flow.Row className="gap-10">
-        <Flow.Node flowId="local">LocalRuntime</Flow.Node>
-        <Flow.Node flowId="external">ExternalStoreRuntime</Flow.Node>
-      </Flow.Row>
-    </Flow.Group>
-  </Flow.Canvas>
-</Flow.Root>
-
-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 |
-| --- | --- | --- |
-| `ai-sdk` | `ExternalStoreRuntime` | Vercel AI SDK v7 (`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

@@ -1,68 +0,0 @@
----
-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 the run until a result is added via `addResult`. 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 | React-component face on `RemoteThreadListAdapter`. Must render children synchronously. `useRemoteThreadListRuntime` renders it when present; the `RemoteThreadList` store entry ignores it. |
-| `unstable_useAdapters` | Various adapters | Hook face on `RemoteThreadListAdapter`. The `RemoteThreadList` store entry calls it. `useRemoteThreadListRuntime` synthesizes a `RuntimeAdapterProvider` from it when `unstable_Provider` is omitted. |
-| `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>