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

package/.docs/raw/docs/{(docs)/guides → guides}/mentions.mdx

@@ -1,6 +1,7 @@
 ---
-title: Mentions
-description: Let users @-mention tools or custom items in the composer to guide the LLM.
+title: Mentions in Chat
+description: Let users @-mention tools or custom items in the AI chat composer to guide the LLM. Mention picker built into assistant-ui's React composer.
+platforms: ["react"]
 ---
 
 Mentions let users type `@` in the composer to open a popover picker, select an item (e.g. a tool), and insert a directive into the message text. The LLM can then use the directive as a hint.
@@ -82,6 +83,63 @@ const myAdapter: Unstable_TriggerAdapter = {
 };
 ```
 
+### Async Mention Search
+
+The adapter interface is synchronous, but the data it reads can come from any async source. Load results into React state (or a query cache) and read the current snapshot inside the adapter methods. The adapter re-creates on each render, so the popover always sees the latest results.
+
+**With React state and `useEffect`:**
+
+```tsx
+import { useState, useEffect, useMemo } from "react";
+import type { Unstable_TriggerAdapter } from "@assistant-ui/core";
+
+function useUserMentionAdapter(query: string) {
+  const [users, setUsers] = useState<{ id: string; name: string }[]>([]);
+
+  useEffect(() => {
+    if (!query) return;
+    let cancelled = false;
+    fetchUsers(query).then((results) => {
+      if (!cancelled) setUsers(results);
+    });
+    return () => { cancelled = true; };
+  }, [query]);
+
+  const adapter: Unstable_TriggerAdapter = useMemo(() => ({
+    categories: () => [],
+    categoryItems: () => [],
+    search: () =>
+      users.map((u) => ({ id: u.id, type: "user", label: u.name })),
+  }), [users]);
+
+  return adapter;
+}
+```
+
+`query` here is the text the user typed after `@`. You can read it from `unstable_useTriggerPopoverScopeContext` if you need it inside the component tree, or pass it as state from a controlled input.
+
+**With React Query:**
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import type { Unstable_TriggerAdapter } from "@assistant-ui/core";
+
+function useMentionAdapter(query: string): Unstable_TriggerAdapter {
+  const { data = [] } = useQuery({
+    queryKey: ["mention-search", query],
+    queryFn: () => fetchUsers(query),
+    enabled: query.length > 0,
+  });
+
+  return useMemo(() => ({
+    categories: () => [],
+    categoryItems: () => [],
+    search: () =>
+      data.map((u) => ({ id: u.id, type: "user", label: u.name })),
+  }), [data]);
+}
+```
+
 Pass the adapter to `TriggerPopover` and declare a `Directive` sub-primitive to bind the insertion behavior:
 
 ```tsx
@@ -333,27 +391,7 @@ import { LexicalComposerInput } from "@assistant-ui/react-lexical";
 
 ## Rendering Mentions in Messages
 
-Use `DirectiveText` as the `Text` component for user messages so directives render as inline chips instead of raw syntax:
-
-```tsx
-import { DirectiveText } from "@/components/assistant-ui/directive-text";
-
-<MessagePrimitive.Parts
-  components={{
-    Text: DirectiveText,
-  }}
-/>
-```
-
-For assistant messages, keep using your markdown renderer (e.g. `MarkdownText`) — the LLM typically does not emit directive syntax.
-
-For a custom formatter, use `createDirectiveText`:
-
-```tsx
-import { createDirectiveText } from "@/components/assistant-ui/directive-text";
-
-const MyDirectiveText = createDirectiveText(myFormatter);
-```
+Use `DirectiveText` as the `Text` component for user messages so directives render as inline chips instead of raw syntax. See the [Directive Text](/docs/ui/directive-text) guide for setup and customization.
 
 ## Processing Mentions on the Backend
 
@@ -467,74 +505,11 @@ Use the trigger popover primitives to build a fully custom popover:
 
 ### Primitives Reference
 
-| Primitive | Description |
-| --- | --- |
-| `Unstable_TriggerPopoverRoot` | Root provider — groups one or more triggers, manages plugin registry |
-| `Unstable_TriggerPopover` | Declares a trigger (id, char, adapter) and renders the popover container |
-| `Unstable_TriggerPopover.Directive` | Behavior sub-primitive — inserts a formatted directive into the composer on selection |
-| `Unstable_TriggerPopover.Action` | Behavior sub-primitive — runs a callback on selection; inserts a chip by default |
-| `Unstable_TriggerPopoverCategories` | Render-function for the top-level category list |
-| `Unstable_TriggerPopoverCategoryItem` | Button that drills into a category (`role="option"`, auto `data-highlighted`) |
-| `Unstable_TriggerPopoverItems` | Render-function for items within the active category or search results |
-| `Unstable_TriggerPopoverItem` | Button that selects an item (`role="option"`, auto `data-highlighted`) |
-| `Unstable_TriggerPopoverBack` | Button that navigates back from items to categories |
-
-See the [Composer API reference](/docs/api-reference/primitives/composer) for full prop details.
+See the [Composer Primitives](/docs/primitives/composer) reference for the full list of trigger popover primitives and their props.
 
 ## Combining with Slash Commands
 
-Mentions and [slash commands](/docs/guides/slash-commands) coexist on the same composer — they're both just triggers on the shared `TriggerPopoverRoot`:
-
-```tsx
-<ComposerPrimitive.Unstable_TriggerPopoverRoot>
-  <ComposerPrimitive.Root>
-    <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
-    <ComposerPrimitive.Send />
-
-    {/* Mention popover (shows on @) */}
-    <ComposerPrimitive.Unstable_TriggerPopover
-      char="@"
-      adapter={mention.adapter}
-    >
-      <ComposerPrimitive.Unstable_TriggerPopover.Directive {...mention.directive} />
-      <ComposerPrimitive.Unstable_TriggerPopoverCategories>
-        {(categories) => categories.map((cat) => (
-          <ComposerPrimitive.Unstable_TriggerPopoverCategoryItem key={cat.id} categoryId={cat.id}>
-            {cat.label}
-          </ComposerPrimitive.Unstable_TriggerPopoverCategoryItem>
-        ))}
-      </ComposerPrimitive.Unstable_TriggerPopoverCategories>
-      <ComposerPrimitive.Unstable_TriggerPopoverItems>
-        {(items) => items.map((item) => (
-          <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item}>
-            {item.label}
-          </ComposerPrimitive.Unstable_TriggerPopoverItem>
-        ))}
-      </ComposerPrimitive.Unstable_TriggerPopoverItems>
-    </ComposerPrimitive.Unstable_TriggerPopover>
-
-    {/* Slash command popover (shows on /) */}
-    <ComposerPrimitive.Unstable_TriggerPopover
-      char="/"
-      adapter={slashAdapter}
-    >
-      <ComposerPrimitive.Unstable_TriggerPopover.Action
-        formatter={unstable_defaultDirectiveFormatter}
-        onExecute={(item) => commandHandlers[item.id]?.()}
-      />
-      <ComposerPrimitive.Unstable_TriggerPopoverItems>
-        {(items) => items.map((item, index) => (
-          <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={index}>
-            {item.label}
-          </ComposerPrimitive.Unstable_TriggerPopoverItem>
-        ))}
-      </ComposerPrimitive.Unstable_TriggerPopoverItems>
-    </ComposerPrimitive.Unstable_TriggerPopover>
-  </ComposerPrimitive.Root>
-</ComposerPrimitive.Unstable_TriggerPopoverRoot>
-```
-
-Each `TriggerPopover` declares its own scope — its popover UI reads state only from that declaration, so `@` and `/` never collide.
+Mentions and slash commands coexist on the same composer. See [Combining Slash Commands and Mentions](/docs/guides/slash-commands#combining-with-mentions) for the full pattern.
 
 ## Related
 

package/.docs/raw/docs/{(docs)/guides → guides}/message-timing.mdx

@@ -1,10 +1,15 @@
 ---
-title: Message Timing
-description: Display stream timing metadata like duration, tokens per second, and time to first token.
+title: Message Timing & Token Stats
+description: Display stream metadata in AI chat — generation duration, tokens per second, and time to first token, rendered via assistant-ui's React components.
+platforms: ["react"]
 ---
 
 Display stream performance metrics — duration, tokens per second, TTFT — on assistant messages.
 
+<Callout type="warn">
+  This feature is experimental. The `useMessageTiming()` API and the set of tracked fields may change in future versions.
+</Callout>
+
 <Callout type="info">
   The [`MessageTiming`](/docs/ui/message-timing) registry component provides a ready-made badge + popover UI. This guide covers the underlying `useMessageTiming()` hook for custom implementations and runtime-specific setup.
 </Callout>
@@ -67,14 +72,15 @@ const AssistantMessage: FC = () => {
 
 | Runtime | Supported | Notes |
 |---------|:-:|-------|
-| DataStream | Yes | Automatic via `AssistantMessageAccumulator` |
+| [Data Stream](/docs/runtimes/custom/data-stream) | Yes | Automatic via `AssistantMessageAccumulator` |
 | AI SDK (`useChatRuntime`) | Yes | Automatic via client-side tracking |
 | Local (`useLocalRuntime`) | Yes | Pass timing in `ChatModelRunResult.metadata` |
 | ExternalStore | Yes | Pass timing in `ThreadMessageLike.metadata` |
-| LangGraph | No | Not yet implemented |
-| AG-UI | No | Not yet implemented |
+| LangGraph | Yes | Automatic via client-side tracking |
+| AG-UI | Yes | Automatic via client-side tracking |
+| OpenCode | Yes | Automatic via client-side tracking |
 
-### DataStream
+### Data Stream
 
 Timing is tracked automatically inside `AssistantMessageAccumulator`. No setup required.
 
@@ -157,6 +163,39 @@ const message: ThreadMessageLike = {
 };
 ```
 
+### LangGraph (`useLangGraphRuntime`)
+
+Timing is tracked automatically on the client side by observing streaming state transitions and `LangChainMessage` content changes. No setup required.
+
+```tsx
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+const runtime = useLangGraphRuntime({ stream: myStream });
+// useMessageTiming() works out of the box
+```
+
+### AG-UI (`useAgUiThreadRuntime`)
+
+Timing is tracked automatically on the client side by the AG-UI run aggregator. Each emitted message includes timing metadata computed from stream chunk observations.
+
+```tsx
+import { useAgUiThreadRuntime } from "@assistant-ui/react-ag-ui";
+
+const runtime = useAgUiThreadRuntime({ runtimeUrl: "..." });
+// useMessageTiming() works out of the box
+```
+
+### OpenCode (`useOpenCodeRuntime`)
+
+Timing is tracked automatically on the client side by observing `OpenCodeThreadState` transitions and assistant message content deltas. No setup required.
+
+```tsx
+import { useOpenCodeRuntime } from "@assistant-ui/react-opencode";
+
+const runtime = useOpenCodeRuntime();
+// useMessageTiming() works out of the box
+```
+
 ## API Reference
 
 ### `useMessageTiming()`

package/.docs/raw/docs/{(docs)/guides → guides}/multi-agent.mdx

@@ -1,6 +1,7 @@
 ---
-title: Multi-Agent
-description: Render sub-agent conversations inside tool call UIs.
+title: Multi-Agent Chat UI
+description: Render sub-agent conversations and handoffs inside tool calls. Build supervisor and multi-agent patterns in a React chat UI with assistant-ui.
+platforms: ["react"]
 ---
 
 In a multi-agent (orchestrator) architecture, a main agent invokes sub-agents via tool calls. Each sub-agent may produce its own conversation (user/assistant messages, tool calls, etc.). assistant-ui supports rendering these nested conversations using the `MessagePartPrimitive.Messages` primitive.
@@ -51,7 +52,10 @@ const ResearchAgentToolUI = makeAssistantToolUI({
 
 ### Provide the Messages from the Backend
 
-Your backend must populate the `messages` field on the tool call result. For example, with the AI SDK:
+Your backend must populate the `messages` field on the tool call result.
+
+<Tabs items={["AI SDK", "LangGraph"]}>
+<Tab value="AI SDK">
 
 ```ts title="api/chat/route.ts"
 tools: {
@@ -62,7 +66,6 @@ tools: {
       const subAgentMessages = await runResearcherAgent(query);
       return {
         answer: subAgentMessages.at(-1)?.content,
-        // The messages field is picked up by assistant-ui
         messages: subAgentMessages,
       };
     },
@@ -70,9 +73,53 @@ tools: {
 },
 ```
 
+</Tab>
+<Tab value="LangGraph">
+
+With `@assistant-ui/react-langgraph`, use `unstable_createLangGraphStream` and set `unstable_allowCancellation: true` to wire up the stop button. When your graph runs a subgraph, the subgraph's messages appear on `ToolCallMessagePart.messages` automatically once you handle the `onSubgraphValues` / `onSubgraphUpdates` events.
+
+```ts title="runtime.ts"
+import {
+  useLangGraphRuntime,
+  unstable_createLangGraphStream,
+} from "@assistant-ui/react-langgraph";
+
+const runtime = useLangGraphRuntime({
+  unstable_allowCancellation: true,
+  stream: unstable_createLangGraphStream({
+    client,
+    assistantId,
+    // "custom" is required for generative UI; "updates" for subgraph events
+    streamMode: ["messages", "updates", "custom"],
+    // abort the run server-side when the user clicks stop
+    onDisconnect: "cancel",
+  }),
+  eventHandlers: {
+    onSubgraphValues: (namespace, values) => {
+      // namespace = e.g. "tools:call_abc" — the sub-agent's node path
+      // values contains the subgraph state, including its messages array
+    },
+    onSubgraphUpdates: (namespace, updates) => {
+      // incremental state updates from the subgraph
+    },
+    onSubgraphError: (namespace, error) => {
+      // error scoped to the subgraph; does not mark the parent message failed
+    },
+    onMessageChunk: (chunk, metadata) => {
+      // metadata.namespace is set when the chunk originates from a subgraph
+      // use it to attribute the chunk to the correct sub-agent
+    },
+  },
+});
+```
+
+See [LangGraph Streaming](/docs/runtimes/langgraph/streaming) for the full event handler reference.
+
+</Tab>
+</Tabs>
+
 <Callout type="info">
-  The exact mechanism for populating `messages` depends on your backend
-  framework. The key requirement is that the tool result's corresponding
+  The key requirement is that the tool result's corresponding
   `ToolCallMessagePart` includes a `messages` array of `ThreadMessage` objects.
 </Callout>
 
@@ -95,6 +142,17 @@ function App() {
   </Step>
 </Steps>
 
+## Subgraph Namespace Events
+
+When using LangGraph, subgraph events carry a `namespace` that identifies which sub-agent emitted them. This lets you attribute messages and state to specific sub-agents without polling or manual coordination.
+
+- `onSubgraphValues(namespace, values)` fires when a subgraph emits a full state snapshot. Use the `values.messages` array to populate `ToolCallMessagePart.messages` for that sub-agent.
+- `onSubgraphUpdates(namespace, updates)` fires for incremental state patches from a subgraph.
+- `onSubgraphError(namespace, error)` fires when a subgraph fails. The parent message is not marked incomplete; only top-level errors trigger that.
+- `onMessageChunk(chunk, metadata)` includes `metadata.namespace` when the chunk originates from a subgraph. Use this to display per-sub-agent streaming indicators.
+
+The `namespace` value mirrors the pipe-separated suffix on the LangGraph event name (e.g. `values|tools:call_abc` gives `"tools:call_abc"`).
+
 ## Recursive Sub-Agents
 
 If a sub-agent's tool calls also have nested messages, the same pattern applies recursively:
@@ -172,3 +230,5 @@ function SubConversation({
 - [Generative UI](/docs/guides/tool-ui) — Creating tool call UIs
 - [MessagePartPrimitive](/docs/api-reference/primitives/message-part) — API reference for message part primitives
 - [Sub-Agent Model Tracking](/docs/cloud/ai-sdk#sub-agent-model-tracking) — Track delegated model usage and costs in the Cloud dashboard
+- [LangGraph Streaming](/docs/runtimes/langgraph/streaming) — Event handlers, subgraph events, and message metadata
+- [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — Structured UI components emitted by your graph

package/.docs/raw/docs/{(docs)/guides → guides}/quoting.mdx

@@ -1,6 +1,7 @@
 ---
 title: Quote Selected Text
-description: Let users select and quote text from messages. Full guide including backend handling and programmatic API.
+description: Let users select text from AI messages and quote it back into the composer. Full quoting flow with backend handling and programmatic API in assistant-ui.
+platforms: ["react"]
 ---
 
 import { QuoteComposerSample } from "@/components/docs/samples/quote-composer";
@@ -9,17 +10,11 @@ import { QuoteComposerSample } from "@/components/docs/samples/quote-composer";
 
 ## Get Started
 
-The **[Quote](/docs/ui/quote)** registry component gives you everything you need out of the box, including a floating selection toolbar, composer quote preview, and inline quote display.
+Install and wire up the `quote` registry component by following the [Quote component page](/docs/ui/quote). It covers the install command, component placement, and the `injectQuoteContext` helper for forwarding quote data to the LLM.
 
-<InstallCommand shadcn={["quote"]} />
-
-It ships three composable pieces:
-
-- **QuoteBlock** renders quoted text inline in user messages
-- **SelectionToolbar** is a floating toolbar that appears on text selection
-- **ComposerQuotePreview** shows the pending quote inside the composer
-
-See the [Quote component page](/docs/ui/quote) for full setup steps and API reference.
+<Callout type="warn">
+  **Limitations:** only one quote can be active at a time. `setQuote` replaces the previous quote instead of appending. The floating toolbar only appears when the selection is entirely within a single message part; cross-message and cross-part selections are ignored.
+</Callout>
 
 ---
 
@@ -132,7 +127,7 @@ function CustomQuoteDisplay() {
 
 ## Programmatic API
 
-Set or clear quotes via the composer runtime:
+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";
@@ -162,12 +157,10 @@ function MyComponent() {
 
 ## Design Notes
 
-- **Single quote:** `setQuote` replaces the current quote instead of appending. Only one quote can be active at a time.
-- **Snapshot text:** The selected text is captured when the quote is created and is not linked to the source message afterward.
-- **Cross-message selection:** The toolbar only appears when the selection stays within a single message.
-- **Streaming messages:** The toolbar still works while a message is streaming because it relies on the captured selection rather than message status.
-- **`isEmpty` unchanged:** A quote by itself does not make the composer non-empty. The user still needs to type a reply.
-- **Scroll hides toolbar:** The toolbar hides on scroll because its position would otherwise become stale.
+- **snapshot text:** the selected text is captured when the quote is created and is not linked to the source message afterward.
+- **streaming messages:** the toolbar still works while a message is streaming because it relies on the captured selection rather than message status.
+- **`isEmpty` unchanged:** a quote by itself does not make the composer non-empty; the user still needs to type a reply.
+- **scroll hides toolbar:** the toolbar hides on scroll because its position would otherwise become stale.
 
 ## Related
 

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

@@ -0,0 +1,212 @@
+---
+title: Resumable Stream Deployment
+description: Production hardening for resumable streams. Authorization, serverless lifetimes, TTLs, key isolation, observability, resource limits, and incident response.
+platforms: ["react"]
+---
+
+This guide assumes you have the basic wiring from [Resumable Streams](/docs/guides/resumable-streams) in place and focuses on what to add before serving production traffic.
+
+## Authentication and authorization
+
+The default resume endpoint serves any caller that knows the `streamId`. Treat the id as opaque, not as a credential. Bind every newly created `streamId` to the requesting user at acquire time and verify the binding on every resume.
+
+Store the binding next to the rest of your session state, or in Redis under a separate key. The example below uses a parallel `<keyPrefix>:owner:<streamId>` entry that mirrors the TTL of the underlying stream.
+
+```ts title="/lib/resumable-context.ts"
+import { createResumableStreamContext } from "assistant-stream/resumable";
+import { redis } from "@/lib/redis";
+import { store } from "@/lib/resumable-store";
+
+const OWNER_PREFIX = "aui:resumable:owner";
+const OWNER_TTL_SEC = 24 * 60 * 60;
+
+export const resumableContext = createResumableStreamContext({ store });
+
+export async function bindStreamToUser(streamId: string, userId: string) {
+  await redis.set(`${OWNER_PREFIX}:${streamId}`, userId, { EX: OWNER_TTL_SEC });
+}
+
+export async function assertStreamOwner(streamId: string, userId: string) {
+  const owner = await redis.get(`${OWNER_PREFIX}:${streamId}`);
+  if (owner !== userId) {
+    throw new Response("Not Found", { status: 404 });
+  }
+}
+```
+
+Wrap `resume` with the ownership check. Returning 404 (not 403) avoids confirming the existence of a stream the caller does not own.
+
+```ts title="/app/api/chat/resume/[streamId]/route.ts"
+import { assertStreamOwner, resumableContext } from "@/lib/resumable-context";
+import { getSessionUserId } from "@/lib/auth";
+
+export async function GET(
+  req: Request,
+  ctx: { params: Promise<{ streamId: string }> },
+) {
+  const userId = await getSessionUserId(req);
+  if (!userId) return new Response("Unauthorized", { status: 401 });
+
+  const { streamId } = await ctx.params;
+  await assertStreamOwner(streamId, userId);
+
+  const stream = await resumableContext.resume(streamId);
+  if (!stream) return new Response("Not Found", { status: 404 });
+
+  return new Response(stream, {
+    headers: { "Content-Type": "text/event-stream" },
+  });
+}
+```
+
+## `waitUntil` on serverless
+
+On Vercel and Cloudflare the request handler is torn down once the response is returned, taking the producer task with it. Without a `waitUntil` hook the persisted stream stops growing the moment the originating request unwinds, so reconnects only see the bytes that happened to land before the response flushed.
+
+On Vercel, pass `after` from `next/server`:
+
+```ts title="/lib/resumable-context.ts"
+import { after } from "next/server";
+import { createResumableStreamContext } from "assistant-stream/resumable";
+import { store } from "@/lib/resumable-store";
+
+export const resumableContext = createResumableStreamContext({
+  store,
+  waitUntil: after,
+});
+```
+
+On Cloudflare Workers, take the `ExecutionContext` from your handler and forward `ctx.waitUntil`:
+
+```ts title="/src/worker.ts"
+import { createResumableStreamContext } from "assistant-stream/resumable";
+import { store } from "./resumable-store";
+
+export default {
+  async fetch(req: Request, env: Env, ctx: ExecutionContext) {
+    const resumableContext = createResumableStreamContext({
+      store,
+      waitUntil: (promise) => ctx.waitUntil(promise),
+    });
+    return handle(req, resumableContext);
+  },
+};
+```
+
+In long-lived Node servers (a custom Express app, a container) `waitUntil` can be omitted; the producer task runs on the same event loop as the handler and is not preempted.
+
+## TTL strategy
+
+Streams expire 24 hours after the last write. The default suits typical chat workloads where a user might reload after lunch, but every deployment should pick a number deliberately.
+
+- Shorten when chunks contain sensitive payloads (PII, drafts, internal documents). A 5 to 30 minute window usually covers reload survival without leaving recoverable bytes around.
+- Extend for long-running agent tasks that may legitimately stretch past a day. Set the TTL above the worst-case task duration so the producer can still finalize.
+- Match TTLs across layers. The store TTL, the owner-binding TTL, and any signed cookie that references `streamId` should expire together; otherwise one outlives the other and either leaks or 404s unexpectedly.
+
+Configure on the store for the global default and on the context for a per-deployment override:
+
+```ts
+import {
+  createInMemoryResumableStreamStore,
+  createResumableStreamContext,
+} from "assistant-stream/resumable";
+
+const store = createInMemoryResumableStreamStore({
+  defaultTtlMs: 30 * 60 * 1000,
+});
+
+export const resumableContext = createResumableStreamContext({
+  store,
+  ttlMs: 30 * 60 * 1000,
+});
+```
+
+The Redis adapters accept the same `defaultTtlMs` option.
+
+## Multi-tenant key isolation
+
+When multiple apps or tenants share a Redis instance, set `keyPrefix` per environment so a misconfigured stream in one tenant cannot collide with, or be deleted alongside, another's. The prefix becomes the leading segment of every meta and data key.
+
+```ts title="/lib/resumable-store.ts"
+import { createClient } from "redis";
+import { createRedisResumableStreamStore } from "assistant-stream/resumable/redis";
+
+const client = createClient({ url: process.env.REDIS_URL });
+await client.connect();
+
+export const store = createRedisResumableStreamStore(client, {
+  keyPrefix: `aui:${process.env.APP_NAME}:${process.env.TENANT_ID}`,
+});
+```
+
+Per-tenant prefixes also make incident response cheaper. A `SCAN MATCH aui:app:tenant-42:*` lets you audit or purge a single tenant without touching the rest.
+
+## 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.
+
+```ts title="/lib/resumable-context.ts"
+import { createResumableStreamContext } from "assistant-stream/resumable";
+import { logger, metrics } from "@/lib/observability";
+import { store } from "@/lib/resumable-store";
+
+export const resumableContext = createResumableStreamContext({
+  store,
+  onAcquire: (streamId, role) => {
+    metrics.increment("resumable.acquire", { role });
+    logger.info("resumable.acquire", { streamId, role });
+  },
+  onAppend: (streamId, byteLength) => {
+    metrics.histogram("resumable.append.bytes", byteLength);
+  },
+  onFinalize: (streamId, status, error) => {
+    metrics.increment("resumable.finalize", { status });
+    logger.info("resumable.finalize", { streamId, status, error });
+  },
+  onError: (streamId, error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error("resumable.error", { streamId, error: message });
+  },
+});
+```
+
+Keep hook bodies cheap. They run on the producer's hot path and any latency they add becomes streaming latency seen by the client.
+
+## Resource limits
+
+The in-memory store enforces three caps that the Redis adapters intentionally leave to the underlying database. Set them whenever your process can be reached by untrusted callers.
+
+```ts
+import { createInMemoryResumableStreamStore } from "assistant-stream/resumable";
+
+const store = createInMemoryResumableStreamStore({
+  maxChunkBytes: 64 * 1024,
+  maxEntriesPerStream: 5000,
+  maxStreams: 10_000,
+});
+```
+
+- `maxChunkBytes` rejects oversized writes from a misbehaving producer (a runaway tool result, a base64 blob accidentally piped through). The producer task fails fast instead of pinning memory.
+- `maxEntriesPerStream` caps the per-stream entry count. This bounds how much any single stream can grow before it starts erroring; pair it with TTLs so finalized streams clear quickly.
+- `maxStreams` caps total live streams. Useful as a backstop in shared development environments and in single-tenant containers; in serverless deployments the platform already constrains concurrency.
+
+These limits exist on the in-memory store. For Redis, configure `maxmemory` and an eviction policy on the server, and rely on application-level rate limiting upstream.
+
+## Incident response
+
+The streamId leaks through response headers, browser session storage, server access logs, and (in some setups) error reports. If you suspect any of those channels were compromised, treat all in-flight stream ids as exposed.
+
+What to log up front, so you have it when you need it:
+
+- The acquiring user id, request id, and IP for every `acquire` call (via `onAcquire`).
+- The finalize status (and any error) for every stream (via `onFinalize`).
+- The owner-binding writes and reads, with the user id and the streamId.
+
+What to rotate or invalidate during an incident:
+
+- Bump `keyPrefix` on the store. Existing streams become unreachable and new ones land under the rotated namespace.
+- Invalidate signed session cookies that reference any cached streamId.
+- Drop the owner-binding keys for affected users (`DEL aui:resumable:owner:*` scoped by user) so resumes are forced through a fresh acquire.
+- Shorten `defaultTtlMs` temporarily so any orphaned stream rolls off quickly.
+
+After rotation, reissue stream ids server-side and redirect clients through a fresh acquire; do not trust any streamId the client already holds.