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

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

@@ -0,0 +1,113 @@
+---
+title: Threads
+description: Basic thread support, AssistantCloud, and custom thread list adapter.
+---
+
+`useLangGraphRuntime` supports the same three-path thread model documented in [threads](/docs/runtimes/concepts/threads), tailored for LangGraph thread ids. This page covers the LangGraph-specific wiring.
+
+## Basic thread support
+
+`useLangGraphRuntime` includes built-in thread management:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => {
+    // initialize() creates or loads a thread and returns its IDs
+    const { remoteId, externalId } = await initialize();
+    // Use externalId (your backend's thread ID) for API calls
+    return sendMessage({ threadId: externalId, messages, config });
+  },
+  create: async () => {
+    // Called when creating a new thread
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+  load: async (externalId) => {
+    // Called when loading an existing thread
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+});
+```
+
+## Cloud persistence
+
+For managed multi-thread support, persistence, sync, and titles, pass an `AssistantCloud` instance:
+
+```ts
+const runtime = useLangGraphRuntime({
+  cloud, // see "AssistantCloud" in /docs/runtimes/concepts/threads
+  // ... stream, create, load functions
+});
+```
+
+See the [cloud persistence guide](/docs/cloud/langgraph) for setup details.
+
+## Custom thread list
+
+To surface pre-existing LangGraph `thread_id`s in the thread picker without running assistant-cloud, pass a `RemoteThreadListAdapter` via `unstable_threadListAdapter`. A common implementation backs `list()` with `client.threads.search()` and `initialize()` with `client.threads.create()`.
+
+```ts
+import type { RemoteThreadListAdapter } from "@assistant-ui/react";
+import { Client } from "@langchain/langgraph-sdk";
+
+const client = new Client({
+  apiUrl: process.env.NEXT_PUBLIC_LANGGRAPH_API_URL,
+});
+
+const threadListAdapter: RemoteThreadListAdapter = {
+  async list() {
+    const threads = await client.threads.search({ limit: 50 });
+    return {
+      threads: threads.map((t) => ({
+        status: "regular",
+        remoteId: t.thread_id,
+        externalId: t.thread_id,
+        title: (t.metadata as { title?: string } | undefined)?.title,
+      })),
+    };
+  },
+  async initialize() {
+    const t = await client.threads.create();
+    return { remoteId: t.thread_id, externalId: t.thread_id };
+  },
+  async delete(remoteId) {
+    await client.threads.delete(remoteId);
+  },
+  // rename, archive, unarchive, fetch, generateTitle — see the threads concept page
+};
+
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) {
+    /* ... */
+  },
+  load: async (externalId) => {
+    /* ... */
+  },
+  unstable_threadListAdapter: threadListAdapter,
+});
+```
+
+Setting `remoteId === externalId` keeps the ids assistant-ui stores aligned with the LangGraph thread ids your `load` and `stream` callbacks receive. See [threads](/docs/runtimes/concepts/threads) for the full adapter contract.
+
+<Callout type="info">
+When `unstable_threadListAdapter` is provided, the `cloud`, `create`, and `delete` options are ignored; the adapter owns the full thread-list lifecycle.
+</Callout>
+
+## Next
+
+<Cards>
+  <Card
+    title="Streaming"
+    description="Event handlers, message metadata, generative UI."
+    href="/docs/runtimes/langgraph/streaming"
+  />
+  <Card
+    title="Threads (concept)"
+    description="General multi-thread model across runtimes."
+    href="/docs/runtimes/concepts/threads"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/langgraph/tutorial/introduction.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Introduction"
+title: Introduction
 description: Build a stockbroker assistant with LangGraph and assistant-ui.
 ---
 
@@ -19,11 +19,11 @@ This agent leverages the following features:
 
 - Node.js 24 or higher
 
-## Final Result
+## Final result
 
 - Demo: https://assistant-ui-stockbroker.vercel.app/
 - Source Code: https://github.com/assistant-ui/assistant-ui-stockbroker
 
-## Get Started
+## Get started
 
 Begin Part 1 of the tutorial by [setting up the frontend](/docs/runtimes/langgraph/tutorial/part-1).

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-1.mdx

@@ -91,26 +91,3 @@ This means you'll see tokens appear smoothly as they're generated by the LLM, wi
 
 Rich text rendering using Markdown is enabled by default.
 
-## Add conversation starter messages
-
-In order to help users understand what the assistant can do, we can add some conversation starter messages.
-
-import Image from "next/image";
-import starter from "./images/conversation-starters.png";
-
-<Image
-  src={starter}
-  alt="Conversation starters"
-  width={600}
-  className="mx-auto rounded-lg border shadow"
-/>
-
-```tsx title="@/app/page.tsx"
-export default function Home() {
-  return (
-    <div className="flex h-full flex-col">
-      <Thread />
-    </div>
-  );
-}
-```

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-2.mdx

@@ -17,7 +17,7 @@ import price from "./images/acme-price.png";
   className="mx-auto rounded-lg border shadow"
 />
 
-For reference, this the corresponding code in the backend:
+For reference, this is the corresponding code in the backend:
 
 https://github.com/assistant-ui/assistant-ui-stockbroker/blob/main/backend/src/tools.ts#L193C1-L216C3
 

package/.docs/raw/docs/runtimes/opencode/hooks.mdx

@@ -0,0 +1,191 @@
+---
+title: Hooks
+description: Permissions, questions, session state, runtime extras.
+---
+
+import { OpenCodeIcon } from "@/components/icons/opencode";
+
+OpenCode-specific React hooks for interacting with the running session. All hooks must be used inside the runtime context (a tree wrapped in `AssistantRuntimeProvider` from a `useOpenCodeRuntime` setup).
+
+## Permissions
+
+OpenCode pauses tool execution to ask the user for permission (e.g. running shell commands, writing files). `useOpenCodePermissions` returns the pending permission requests and a reply function:
+
+```tsx
+import { useOpenCodePermissions } from "@assistant-ui/react-opencode";
+
+function PermissionPrompt() {
+  const { pending, reply } = useOpenCodePermissions();
+
+  return pending.map((req) => (
+    <div key={req.id}>
+      <p>
+        Allow <code>{req.toolName}</code>: {req.title ?? req.permission}?
+      </p>
+      <button onClick={() => reply(req.id, "once")}>Allow once</button>
+      <button onClick={() => reply(req.id, "always")}>Always allow</button>
+      <button onClick={() => reply(req.id, "reject")}>Reject</button>
+    </div>
+  ));
+}
+```
+
+Return shape:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `pending` | `OpenCodePermissionRequest[]` | Permission requests waiting for a reply. |
+| `reply` | `(id, response) => Promise<void>` | Send a reply for a pending permission. |
+
+Reply values:
+
+| Reply | Meaning |
+| --- | --- |
+| `"once"` | Approve this single permission request. |
+| `"always"` | Approve this permission and remember the choice. |
+| `"reject"` | Deny the permission; the tool call is cancelled. |
+
+## Questions
+
+OpenCode can ask interactive questions during a run. `useOpenCodeQuestions` returns the pending questions as an array:
+
+```tsx
+import {
+  useOpenCodeQuestions,
+  useOpenCodeRuntimeExtras,
+} from "@assistant-ui/react-opencode";
+
+function QuestionPrompt() {
+  const questions = useOpenCodeQuestions();
+  const { replyToQuestion, rejectQuestion } = useOpenCodeRuntimeExtras();
+
+  return questions.map((req) => (
+    <div key={req.id}>
+      <p>{req.text}</p>
+      <button
+        onClick={() =>
+          replyToQuestion(req.id, [
+            /* QuestionAnswer[] from @opencode-ai/sdk */
+          ])
+        }
+      >
+        Answer
+      </button>
+      <button onClick={() => rejectQuestion(req.id)}>Skip</button>
+    </div>
+  ));
+}
+```
+
+To reply, use `replyToQuestion(id, answers)` or `rejectQuestion(id)` from [`useOpenCodeRuntimeExtras`](#runtime-extras).
+
+## Session
+
+`useOpenCodeSession` returns the current OpenCode `Session` object (server-side session metadata):
+
+```tsx
+import { useOpenCodeSession } from "@assistant-ui/react-opencode";
+
+function SessionInfo() {
+  const session = useOpenCodeSession();
+  if (!session) return null;
+  return <div>Session: {session.id}</div>;
+}
+```
+
+## Thread state
+
+`useOpenCodeThreadState` returns the full projected thread state (messages, run state, interactions, sync metadata). Use it for advanced custom views; most apps don't need it.
+
+```tsx
+import { useOpenCodeThreadState } from "@assistant-ui/react-opencode";
+
+function RunStatus() {
+  const state = useOpenCodeThreadState();
+  return <div>Run: {state.runState.type}</div>;
+}
+```
+
+The returned `OpenCodeThreadState` includes:
+
+- `sessionId`, `session`, `sessionStatus`, `loadState`, `runState`
+- `messageOrder`, `messagesById`, `pendingUserMessages`
+- `interactions.permissions` (pending + resolved), `interactions.questions` (pending + answered + rejected)
+- `unhandledEvents`, `sync` timestamps
+
+You can also pass a selector to read a specific slice:
+
+```tsx
+const isStreaming = useOpenCodeThreadState((s) => s.runState.type === "streaming");
+```
+
+## Runtime extras
+
+`useOpenCodeRuntimeExtras` exposes session-level imperative actions:
+
+```tsx
+import { useOpenCodeRuntimeExtras } from "@assistant-ui/react-opencode";
+
+function SessionActions() {
+  const {
+    fork,
+    revert,
+    unrevert,
+    cancel,
+    refresh,
+    replyToPermission,
+    replyToQuestion,
+    rejectQuestion,
+  } = useOpenCodeRuntimeExtras();
+  // ...
+}
+```
+
+| Action | Description |
+| --- | --- |
+| `fork(messageId)` | Create a new session forked from the given message; returns the new session id. |
+| `revert(messageId)` | Revert the session to the state at the given message. |
+| `unrevert()` | Undo the last revert. |
+| `cancel()` | Cancel an in-flight run. |
+| `refresh()` | Force re-fetch of session messages. |
+| `replyToPermission(id, response)` | Reply to a permission request (`"once"`, `"always"`, `"reject"`). |
+| `replyToQuestion(id, answers)` | Answer a pending question. |
+| `rejectQuestion(id)` | Reject a pending question. |
+
+`useOpenCodePermissions` and `useOpenCodeQuestions` are sugar over `replyToPermission` / `replyToQuestion` / `rejectQuestion` plus the `pending` slices of state.
+
+## Lower-level building blocks
+
+For custom integrations that bypass `useOpenCodeRuntime`:
+
+| Export | Purpose |
+| --- | --- |
+| `OpenCodeEventSource` | Wraps the OpenCode server's event stream into a typed subscription. |
+| `OpenCodeThreadController` | Per-session controller managing message state. |
+| `createOpenCodeThreadState`, `reduceOpenCodeThreadState` | Pure state reducers if you want to drive the state machine yourself. |
+| `projectOpenCodeThreadMessages` | Project raw OpenCode messages into assistant-ui thread messages. |
+| `createOpencodeClient` (re-exported from `@opencode-ai/sdk`) | Build a client with custom config. |
+
+These are only needed for advanced cases; most apps should use `useOpenCodeRuntime` directly.
+
+## Related
+
+<Cards>
+  <Card
+    icon={<OpenCodeIcon width={20} height={20} />}
+    title="OpenCode overview"
+    description="What OpenCode is and when to pick it."
+    href="/docs/runtimes/opencode"
+  />
+  <Card
+    title="Quickstart"
+    description="Minimal runtime + Thread setup."
+    href="/docs/runtimes/opencode/quickstart"
+  />
+  <Card
+    icon={<OpenCodeIcon width={20} height={20} />}
+    title="OpenCode docs"
+    description="The OpenCode server itself."
+    href="https://opencode.ai/"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/opencode/overview.mdx

@@ -0,0 +1,48 @@
+---
+title: Overview
+description: Connect to an OpenCode coding-agent server.
+---
+
+`@assistant-ui/react-opencode` is a runtime adapter for [OpenCode](https://opencode.ai/), an open-source AI coding agent. It wires the OpenCode server's session and event APIs into an assistant-ui thread, including tool permissions, interactive questions, and session state.
+
+<Callout type="warn">
+This adapter is at v0.0.3 and is experimental. The runtime API and exported hooks may change without notice.
+</Callout>
+
+## When to use it
+
+Pick the OpenCode runtime when:
+
+- You are building a UI on top of an OpenCode agent server.
+- You need first-class support for OpenCode's permission and question flows.
+- You want session-aware features: fork, revert, unrevert, refresh.
+
+If your backend is not OpenCode-based, see [picking a runtime](/docs/runtimes/pick-a-runtime) for alternatives.
+
+## Architecture
+
+`@assistant-ui/react-opencode` is layered on `ExternalStoreRuntime` plus a `RemoteThreadList` for session-backed thread management (see [architecture](/docs/runtimes/concepts/architecture)). OpenCode sessions map to assistant-ui threads; the runtime subscribes to a server-sent event stream and projects messages into the thread.
+
+## Requirements
+
+- A running [OpenCode](https://opencode.ai/) server (defaults to `http://localhost:4096`).
+- React 18 or 19.
+
+## Install
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-opencode", "@opencode-ai/sdk"]} />
+
+## Next
+
+<Cards>
+  <Card
+    title="Quickstart"
+    description="Minimal useOpenCodeRuntime setup against a local OpenCode server."
+    href="/docs/runtimes/opencode/quickstart"
+  />
+  <Card
+    title="Hooks"
+    description="Permissions, questions, session state, runtime extras."
+    href="/docs/runtimes/opencode/hooks"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/opencode/quickstart.mdx

@@ -0,0 +1,119 @@
+---
+title: Quickstart
+description: Minimal useOpenCodeRuntime setup against a local OpenCode server.
+---
+
+Three steps to a working chat against a local OpenCode server. Assumes you have OpenCode running; if not, follow [opencode.ai](https://opencode.ai/) to install and start the server first.
+
+<Steps>
+<Step>
+
+### Wire up the runtime provider
+
+```tsx title="app/MyRuntimeProvider.tsx"
+"use client";
+
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useOpenCodeRuntime } from "@assistant-ui/react-opencode";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const runtime = useOpenCodeRuntime({
+    baseUrl: "http://localhost:4096",
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`baseUrl` defaults to `http://localhost:4096` if omitted.
+
+</Step>
+<Step>
+
+### Render the Thread
+
+```tsx title="app/page.tsx"
+import { Thread } from "@assistant-ui/react";
+import { MyRuntimeProvider } from "./MyRuntimeProvider";
+
+export default function Page() {
+  return (
+    <MyRuntimeProvider>
+      <Thread />
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Step>
+<Step>
+
+### Set up UI components
+
+Follow the [UI Components guide](/docs/ui/thread) to wire up the Thread, composer, and supporting primitives.
+
+</Step>
+</Steps>
+
+The runtime opens an SSE event stream against the OpenCode server, listens for session and message events, and projects them into the thread. Each OpenCode session corresponds to one thread; the thread list reflects sessions on the server.
+
+## Default model and agent
+
+Pin a default model or agent when starting new sessions:
+
+```tsx
+const runtime = useOpenCodeRuntime({
+  baseUrl: "http://localhost:4096",
+  defaultModel: { providerID: "anthropic", modelID: "claude-sonnet-4" },
+  defaultAgent: "coder",
+});
+```
+
+## Bring your own client
+
+If you need a pre-configured `OpencodeClient` (e.g. for auth headers), pass it directly:
+
+```tsx
+import { createOpencodeClient } from "@assistant-ui/react-opencode";
+
+const client = createOpencodeClient({
+  baseUrl: "http://localhost:4096",
+  // additional client config...
+});
+
+const runtime = useOpenCodeRuntime({ client });
+```
+
+## Resuming a session
+
+Pass `initialSessionId` to open the runtime against an existing session on first load:
+
+```tsx
+const runtime = useOpenCodeRuntime({
+  baseUrl: "http://localhost:4096",
+  initialSessionId: "ses_abc123",
+});
+```
+
+## Next
+
+<Cards>
+  <Card
+    title="Hooks"
+    description="Permissions, questions, session state, runtime extras."
+    href="/docs/runtimes/opencode/hooks"
+  />
+  <Card
+    title="Pick a runtime"
+    description="Compare OpenCode to other runtime options."
+    href="/docs/runtimes/pick-a-runtime"
+  />
+</Cards>