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

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.

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

@@ -0,0 +1,152 @@
+---
+title: Custom Resumable Stream Stores
+description: Implement the ResumableStreamStore interface to back resumable streams with Postgres, Cloudflare Durable Objects, Upstash REST, InstantDB, or any other backend.
+platforms: ["react"]
+---
+
+The built-in InMemory and Redis adapters cover most deployments. Write your own `ResumableStreamStore` when you need a backend you already operate (Postgres, MySQL), an edge-native primitive (Cloudflare Durable Objects, Workers KV), an HTTP-only key-value service (Upstash REST), or a realtime database (InstantDB). The contract is six async methods over an opaque `streamId` and a monotonic byte log.
+
+## Interface walkthrough
+
+The full interface lives in `assistant-stream/resumable`:
+
+```ts title="packages/assistant-stream/src/resumable/types.ts"
+export interface ResumableStreamStore {
+  acquire(
+    streamId: string,
+    options?: ResumableStreamAcquireOptions,
+  ): Promise<ResumableStreamRole>;
+  append(streamId: string, chunk: Uint8Array): Promise<void>;
+  finalize(
+    streamId: string,
+    status: "done" | "error",
+    error?: string,
+  ): Promise<void>;
+  read(
+    streamId: string,
+    cursor: string,
+    signal: AbortSignal,
+  ): AsyncIterable<ResumableStreamEntry>;
+  status(streamId: string): Promise<ResumableStreamStatus>;
+  delete(streamId: string): Promise<void>;
+}
+```
+
+`acquire(streamId, options?)` arbitrates ownership. The first caller for a given `streamId` resolves to `"producer"`; every later caller, including those arriving after `finalize`, resolves to `"consumer"`. Implementations must perform the check and the insert atomically (see below). `options.ttlMs` overrides the store default for this stream; honor it when you set the expiration timestamp.
+
+`append(streamId, chunk)` adds a `Uint8Array` to the log under a fresh, monotonically increasing cursor. Callers expect the chunk to be observable to `read` before the promise resolves. Implementations should refresh the TTL on each call so a stream that is still actively producing does not expire mid-flight, and should reject when the stream is missing or already finalized.
+
+`finalize(streamId, status, error?)` flips the stream into a terminal state. Pending and future `read` iterables drain buffered entries and then either complete (`"done"`) or throw with `error` (`"error"`). Implementations must make `finalize` idempotent: a duplicate call with the same status is a no-op, and the producer task may retry on transient errors.
+
+`read(streamId, cursor, signal)` is the only streaming method. It yields every entry whose cursor sorts strictly after the supplied `cursor`, then waits for new appends, then completes when the stream finalizes. Aborting `signal` resolves the iterable cleanly without throwing. Networked stores typically combine a bounded fetch loop with pub/sub, long-poll, or notify wakeups; do not busy-loop.
+
+`status(streamId)` returns one of `"streaming" | "done" | "error" | "missing"` synchronously with respect to the underlying store. It exists so the context can decide whether to start a new producer or attach a consumer without holding a `read` iterator open.
+
+`delete(streamId)` removes all state for the stream. It must be a no-op when the stream does not exist, and it should cause active `read` iterables to terminate (treat outstanding readers as if the stream finalized).
+
+## Acquire semantics
+
+`acquire` is the only method that requires linearizability across processes. Two route handlers that race to start the same `streamId` must see exactly one `"producer"` result; the loser becomes a `"consumer"` and replays the winner's bytes. A single-process store can guard a `Map` with a synchronous `if (!map.has(id)) map.set(id, ...)`. Networked stores need a primitive that does the check and the insert in one round trip:
+
+- Redis: `SET key value NX EX ttl`, or `INCR` against a per-stream counter.
+- Postgres: `INSERT ... ON CONFLICT (stream_id) DO NOTHING RETURNING ...`.
+- Durable Objects: a single object instance per `streamId` plus a boolean field.
+- Upstash REST: `set` with `nx=true`.
+
+If your backend cannot offer atomicity, do not paper over it with read-then-write; you will silently produce two writers for the same stream under contention, and consumers will observe interleaved bytes.
+
+## The cursor contract
+
+Cursors are opaque strings. Callers never inspect them; the store assigns them, the context echoes them back on the next `read` call, and the store uses them to resume from the correct position. Two rules:
+
+- Cursors must be strictly monotonic per stream. Whatever scheme you pick (sequence number, ULID, Postgres `bigserial`, Redis stream id), entry N+1 sorts after entry N.
+- The empty string means start from the beginning. `read(streamId, "", signal)` yields every entry the store has, oldest first.
+
+You do not need cross-stream ordering. You do need a deterministic mapping from cursor back to position so that `read` can resume a consumer that disconnected mid-replay.
+
+## A worked example
+
+A `Map`-backed implementation suitable for a single-process server. It is deliberately small and skips TTL eviction; treat it as a starting point for a custom backend rather than a replacement for `createInMemoryResumableStreamStore`.
+
+```ts title="/lib/map-resumable-store.ts"
+import type { ResumableStreamStore } from "assistant-stream/resumable";
+
+type State = {
+  entries: { cursor: string; chunk: Uint8Array }[];
+  seq: number;
+  final?: { status: "done" | "error"; error?: string };
+  waiters: Array<() => void>;
+};
+
+export function createMapResumableStreamStore(): ResumableStreamStore {
+  const streams = new Map<string, State>();
+  const wake = (s: State) => s.waiters.splice(0).forEach((fn) => fn());
+  return {
+    async acquire(id) {
+      if (streams.has(id)) return "consumer";
+      streams.set(id, { entries: [], seq: 0, waiters: [] });
+      return "producer";
+    },
+    async append(id, chunk) {
+      const s = streams.get(id);
+      if (!s || s.final) throw new Error(`Cannot append: ${id}`);
+      s.entries.push({ cursor: (++s.seq).toString(36), chunk });
+      wake(s);
+    },
+    async finalize(id, status, error) {
+      const s = streams.get(id);
+      if (!s || s.final) return;
+      s.final = { status, error };
+      wake(s);
+    },
+    async *read(id, cursor, signal) {
+      const s = streams.get(id);
+      if (!s) throw new Error(`Stream not found: ${id}`);
+      let i = cursor === "" ? 0 : Number.parseInt(cursor, 36);
+      while (!signal.aborted) {
+        while (i < s.entries.length) yield s.entries[i++]!;
+        if (s.final) {
+          if (s.final.status === "error") throw new Error(s.final.error);
+          return;
+        }
+        await new Promise<void>((r) => {
+          s.waiters.push(r);
+          signal.addEventListener("abort", () => r(), { once: true });
+        });
+      }
+    },
+    async status(id) {
+      const s = streams.get(id);
+      return !s ? "missing" : s.final ? s.final.status : "streaming";
+    },
+    async delete(id) {
+      const s = streams.get(id);
+      if (!s) return;
+      streams.delete(id);
+      s.final ??= { status: "done" };
+      wake(s);
+    },
+  };
+}
+```
+
+## TTL and eviction
+
+`acquire` receives `options.ttlMs`; if absent, fall back to a store-level default (the built-in stores use 24 hours). Refresh the expiration on every `append` and on `finalize` so a stream that finishes near the deadline still has time to be consumed. Persist the TTL alongside the entries so a worker reading the stream much later can decide whether the data is still valid.
+
+When a stream expires, treat it the same as `finalize(streamId, "error", "Stream expired")`: any active `read` iterable must throw or terminate, and `status` must transition to `"missing"` once the eviction has run. Stores backed by Redis or a similar TTL-aware engine can lean on the engine's own expiration; SQL-backed stores need a periodic sweep, and Durable Objects can use `setAlarm`.
+
+## Wiring it up
+
+`createResumableStreamContext` takes any object that satisfies `ResumableStreamStore`. There is no registry and no extra configuration; pass your instance as `store`:
+
+```ts title="/lib/resumable-context.ts"
+import { createResumableStreamContext } from "assistant-stream/resumable";
+import { createMapResumableStreamStore } from "@/lib/map-resumable-store";
+
+export const resumableContext = createResumableStreamContext({
+  store: createMapResumableStreamStore(),
+});
+```
+
+From this point the route handlers in [Resumable Streams](/docs/guides/resumable-streams) work unchanged: `resumableContext.run(streamId, makeStream)` calls your `acquire`, `append`, and `finalize`, and `resumableContext.resume(streamId)` calls your `read`.

package/.docs/raw/docs/guides/resumable-streams.mdx

@@ -0,0 +1,210 @@
+---
+title: "Resumable Streams"
+description: Persist an in-flight LLM response on the server so the client can reload, lose its connection, or open a new tab and pick up the same stream.
+platforms: ["react"]
+---
+
+`assistant-stream/resumable` lets you continue a streaming LLM response across client reconnects. The server keeps writing to a store while the original request is in flight; if the browser reloads or loses its connection, a follow-up request replays the persisted bytes plus any new ones until the producer finalizes.
+
+It works with any encoder that already ships in `assistant-stream` (the AI SDK UI message stream, the data stream protocol, the assistant transport SSE format, or your own), because persistence happens at the byte level after encoding.
+
+## What it solves
+
+A user sends a long prompt, walks away, and reloads the tab. Without resumable streams the LLM call is wasted; with them the client picks up where it left off. The same flow handles dropped mobile connections and lets a stream started on one device be read on another, gated by an opaque stream id.
+
+If your responses are short or you do not care about reload survival, the standard `streamText().toUIMessageStreamResponse()` path is enough.
+
+## Server side: minimum wiring
+
+Construct a `ResumableStreamContext` once per process and reuse it across requests. The context is the seam between your route handlers and the storage backend.
+
+```ts title="/lib/resumable-context.ts"
+import {
+  createInMemoryResumableStreamStore,
+  createResumableStreamContext,
+} from "assistant-stream/resumable";
+
+const store = createInMemoryResumableStreamStore();
+export const resumableContext = createResumableStreamContext({ store });
+```
+
+In your chat route, wrap the response body in `ctx.run(streamId, makeStream)`. The first caller for `streamId` becomes the producer (your `makeStream` callback runs); later callers and reconnects become consumers that replay the persisted bytes.
+
+```ts title="/app/api/chat/route.ts"
+import { streamText } from "ai";
+import { RESUMABLE_STREAM_ID_HEADER } from "assistant-stream/resumable";
+import { resumableContext } from "@/lib/resumable-context";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const streamId = crypto.randomUUID();
+
+  const result = streamText({ /* model, messages, tools, ... */ });
+  const sourceBody = result.toUIMessageStreamResponse().body!;
+
+  const stream = await resumableContext.run(streamId, () => sourceBody);
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      [RESUMABLE_STREAM_ID_HEADER]: streamId,
+    },
+  });
+}
+```
+
+A separate GET endpoint replays the persisted bytes for reconnecting clients. `ctx.resume(streamId)` returns `null` when no stream exists; use `ctx.requireResume(streamId)` if you prefer to surface a `ResumableStreamError` with code `"missing"` instead.
+
+```ts title="/app/api/chat/resume/[streamId]/route.ts"
+import { RESUMABLE_STREAM_ID_HEADER } from "assistant-stream/resumable";
+import { resumableContext } from "@/lib/resumable-context";
+
+export async function GET(
+  _req: Request,
+  ctx: { params: Promise<{ streamId: string }> },
+) {
+  const { streamId } = await ctx.params;
+  const stream = await resumableContext.resume(streamId);
+  if (!stream) {
+    return new Response(JSON.stringify({ error: "stream not found" }), {
+      status: 404,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      [RESUMABLE_STREAM_ID_HEADER]: streamId,
+    },
+  });
+}
+```
+
+The context exposes two more verbs: `ctx.status(streamId)` returns `"streaming" | "done" | "error" | "missing"`, and `ctx.delete(streamId)` removes all persisted state for a stream and terminates active readers. The remaining options on `createResumableStreamContext` (`onAcquire`, `onAppend`, `onFinalize`, `onError`) are observability hooks covered in [Resumable Stream Deployment](/docs/guides/resumable-stream-deployment).
+
+## Client side: native integration
+
+`@assistant-ui/react-ai-sdk` ships a `resumable` option on `AssistantChatTransport`. It captures the stream id from the response header, redirects `chat.resumeStream()` reconnects to your resume route, and clears the stored id when the response finishes naturally. Pair it with `useChatRuntime`, which fires `chat.resumeStream()` on mount whenever a pending id is present in storage.
+
+```tsx title="/app/page.tsx"
+"use client";
+
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  AssistantChatTransport,
+  createResumableSessionStorage,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+import { useMemo } from "react";
+import { Thread } from "@/components/assistant-ui/thread";
+
+const storage = createResumableSessionStorage();
+
+export default function Page() {
+  const transport = useMemo(
+    () =>
+      new AssistantChatTransport({
+        api: "/api/chat",
+        resumable: {
+          storage,
+          resumeApi: (streamId) => `/api/chat/resume/${streamId}`,
+        },
+      }),
+    [],
+  );
+  const runtime = useChatRuntime({ transport });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`createResumableSessionStorage` returns a `ResumableClientStorage` backed by `window.sessionStorage`. Pass `{ key }` to namespace per route or per chat surface, or supply your own implementation of the three methods (`getStreamId`, `setStreamId`, `clear`). If you are running on a transport that already wraps `fetch` or `prepareReconnectToStreamRequest`, the `resumable` option composes with your existing handlers.
+
+The default finish detector scans the SSE body for the AI SDK `"type":"finish"` marker. Override `isFinishEvent` on the `resumable` option when you ship a custom encoder.
+
+## Storage choices
+
+The core package ships `createInMemoryResumableStreamStore` for development and tests. State lives in a process-local `Map`, so it does not survive a server restart. Useful options include `defaultTtlMs`, `maxChunkBytes`, `maxEntriesPerStream`, `maxStreams`, and `gcIntervalMs` for periodic eviction.
+
+For production, use one of the optional Redis adapters via the `assistant-stream/resumable/redis` (node-redis v5) or `assistant-stream/resumable/ioredis` sub-paths. Both adapters batch the per-append `XADD` and TTL refresh into a single pipelined round trip, store chunk values as binary, and accept the same `keyPrefix`, `defaultTtlMs`, `pollIntervalMs`, and `maxChunkBytes` options. Cluster routing works because each stream's keys share a `{streamId}` hash tag.
+
+```ts title="/lib/resumable-context.ts"
+import {
+  createResumableStreamContext,
+  type ResumableStreamStore,
+} from "assistant-stream/resumable";
+
+async function createStore(): Promise<ResumableStreamStore> {
+  if (!process.env.REDIS_URL) {
+    const { createInMemoryResumableStreamStore } = await import(
+      "assistant-stream/resumable"
+    );
+    return createInMemoryResumableStreamStore();
+  }
+  const { createClient } = await import("redis");
+  const { createRedisResumableStreamStore } = await import(
+    "assistant-stream/resumable/redis"
+  );
+  const client = createClient({ url: process.env.REDIS_URL });
+  await client.connect();
+  return createRedisResumableStreamStore(client);
+}
+
+export const resumableContext = createResumableStreamContext({
+  store: await createStore(),
+});
+```
+
+For Postgres, Cloudflare Durable Objects, Upstash REST, or any other backend, implement the `ResumableStreamStore` interface directly. See [Custom Resumable Stream Stores](/docs/guides/resumable-stream-stores) for the contract walkthrough and a worked example.
+
+## Production checklist
+
+- **Auth.** The resume route in the snippets above will serve any caller that knows the stream id. Bind `streamId` to the requesting user at acquire time and verify the binding inside the resume handler. Treat the id as opaque, not as a credential; it leaks via response headers, `sessionStorage`, browser history, and access logs.
+- **`waitUntil` on serverless.** On Vercel and Cloudflare the request handler is killed once the response returns, which interrupts the producer task. Pass `after` from `next/server` (or your platform's `ctx.waitUntil`) when constructing the context so the task survives past the response: `createResumableStreamContext({ store, waitUntil: after })`.
+- **TTL.** Streams expire 24 hours after the last write by default. Configure with `defaultTtlMs` on the store, or override per deployment via `ttlMs` on the context. Match TTLs across the store, any owner-binding key, and any signed cookie that references a `streamId`.
+- **Stream id format.** The Redis adapters validate `streamId` against `/^[A-Za-z0-9_.:-]{1,256}$/` to keep keys well-formed. UUIDv4 is fine.
+
+For the full treatment of authorization, multi-tenant key prefixes, observability hooks, resource limits, and incident response, see [Resumable Stream Deployment](/docs/guides/resumable-stream-deployment).
+
+A new `ResumableStreamError` class is exported from `assistant-stream/resumable` with codes `"missing" | "exists" | "finalized" | "invalid-id"`; catch it in the resume route to distinguish "stream gone" from other failures.
+
+## Helpers for `AssistantStreamController` callbacks
+
+If you produce streams via `createAssistantStream` rather than the AI SDK, the package ships two helpers that bridge the controller-callback style and any encoder to the store:
+
+```ts
+import {
+  createResumableAssistantStreamResponse,
+  createResumeAssistantStreamResponse,
+} from "assistant-stream/resumable";
+import { resumableContext } from "@/lib/resumable-context";
+
+// POST handler
+return createResumableAssistantStreamResponse({
+  context: resumableContext,
+  streamId,
+  callback: (controller) => {
+    /* same shape as createAssistantStreamResponse */
+  },
+});
+
+// GET resume handler
+return createResumeAssistantStreamResponse({
+  context: resumableContext,
+  streamId,
+});
+```
+
+Both helpers default to the data-stream encoder; pass `encoder: () => new AssistantTransportEncoder()` (or any custom encoder) to override. They set the `x-resumable-stream-id` response header automatically, which is what `AssistantChatTransport`'s `resumable` adapter looks for.
+
+## Example app
+
+[`examples/with-resumable-stream`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-resumable-stream) is a runnable Next.js app that uses `useChat`, the `resumable` transport option, and `useChatRuntime`. It falls back to a built-in mock when `OPENAI_API_KEY` is unset, and switches the store from in-memory to Redis when `REDIS_URL` is set.
+
+```sh
+npx assistant-ui create my-app -e with-resumable-stream
+```

package/.docs/raw/docs/guides/slash-commands.mdx

@@ -1,6 +1,6 @@
 ---
 title: Slash Commands
-description: Let users type / in the composer to trigger predefined actions from a popover picker.
+description: Trigger predefined actions in your AI chat by typing / — slash command palette with popover, search, and action handlers in React via assistant-ui.
 platforms: ["react"]
 ---
 

package/.docs/raw/docs/guides/speech.mdx

@@ -1,6 +1,6 @@
 ---
-title: Text-to-Speech (Speech Synthesis)
-description: Read messages aloud with Web Speech API or a custom TTS adapter.
+title: Text-to-Speech for Chat
+description: Read AI chat messages aloud with the Web Speech API or a custom TTS adapter. Speech synthesis for React chat UIs, integrated with assistant-ui.
 platforms: ["react"]
 ---