chat 4.20.2 → 4.22.0

package/dist/{jsx-runtime-C2ATKxHQ.d.ts → jsx-runtime-DraWieqP.d.ts}

@@ -729,4 +729,4 @@ declare namespace JSX {
     }
 }
 
-export { type DividerProps as $, type ActionsComponent as A, type ButtonComponent as B, type CardElement as C, type DividerComponent as D, type ImageElement as E, type FieldComponent as F, type LinkButtonElement as G, type LinkButtonOptions as H, type ImageComponent as I, type LinkElement as J, type SectionElement as K, type LinkButtonComponent as L, type ModalElement as M, type TableAlignment as N, type TableElement as O, type TableOptions as P, type TextElement as Q, type RadioSelectComponent as R, type SectionComponent as S, type TextComponent as T, type TextStyle as U, type ButtonProps as V, type CardJSXElement as W, type CardJSXProps as X, type CardLinkProps as Y, type CardProps as Z, type ContainerProps as _, type ChatElement as a, type FieldProps as a0, type ImageProps as a1, type LinkButtonProps as a2, type ModalProps as a3, type SelectOptionProps as a4, type SelectProps as a5, type TextInputProps as a6, type TextProps as a7, type ModalChild as a8, type ModalOptions as a9, type RadioSelectElement as aa, type RadioSelectOptions as ab, type SelectElement as ac, type SelectOptionElement as ad, type SelectOptions as ae, type TextInputElement as af, type TextInputOptions as ag, type TableProps as ah, type TableComponent as ai, isCardLinkProps as aj, jsx as ak, jsxs as al, jsxDEV as am, Fragment as an, JSX as ao, type CardChild as b, type CardComponent as c, cardChildToFallbackText as d, type CardLinkComponent as e, type FieldsComponent as f, fromReactElement as g, isJSX as h, isCardElement as i, Table as j, toModalElement as k, fromReactModalElement as l, isModalElement as m, type ModalComponent as n, type SelectComponent as o, type SelectOptionComponent as p, type TextInputComponent as q, type ActionsElement as r, type ButtonElement as s, toCardElement as t, type ButtonOptions as u, type ButtonStyle as v, type CardOptions as w, type DividerElement as x, type FieldElement as y, type FieldsElement as z };
+export { type DividerProps as $, type ActionsComponent as A, type ButtonComponent as B, type ChatElement as C, type DividerComponent as D, type ImageElement as E, type FieldComponent as F, type LinkButtonElement as G, type LinkButtonOptions as H, type ImageComponent as I, type LinkElement as J, type SectionElement as K, type LinkButtonComponent as L, type ModalElement as M, type TableAlignment as N, type TableElement as O, type TableOptions as P, type TextElement as Q, type RadioSelectComponent as R, type SectionComponent as S, type TextComponent as T, type TextStyle as U, type ButtonProps as V, type CardJSXElement as W, type CardJSXProps as X, type CardLinkProps as Y, type CardProps as Z, type ContainerProps as _, type CardElement as a, type FieldProps as a0, type ImageProps as a1, type LinkButtonProps as a2, type ModalProps as a3, type SelectOptionProps as a4, type SelectProps as a5, type TextInputProps as a6, type TextProps as a7, type ModalChild as a8, type ModalOptions as a9, type RadioSelectElement as aa, type RadioSelectOptions as ab, type SelectElement as ac, type SelectOptionElement as ad, type SelectOptions as ae, type TextInputElement as af, type TextInputOptions as ag, type TableProps as ah, type TableComponent as ai, isCardLinkProps as aj, jsx as ak, jsxs as al, jsxDEV as am, Fragment as an, JSX as ao, type CardChild as b, type CardComponent as c, cardChildToFallbackText as d, type CardLinkComponent as e, type FieldsComponent as f, fromReactElement as g, isJSX as h, isCardElement as i, Table as j, toModalElement as k, fromReactModalElement as l, isModalElement as m, type ModalComponent as n, type SelectComponent as o, type SelectOptionComponent as p, type TextInputComponent as q, type ActionsElement as r, type ButtonElement as s, toCardElement as t, type ButtonOptions as u, type ButtonStyle as v, type CardOptions as w, type DividerElement as x, type FieldElement as y, type FieldsElement as z };

package/dist/jsx-runtime.d.ts

@@ -1 +1 @@
-export { A as ActionsComponent, B as ButtonComponent, V as ButtonProps, c as CardComponent, W as CardJSXElement, X as CardJSXProps, e as CardLinkComponent, Y as CardLinkProps, Z as CardProps, a as ChatElement, _ as ContainerProps, D as DividerComponent, $ as DividerProps, F as FieldComponent, a0 as FieldProps, f as FieldsComponent, an as Fragment, I as ImageComponent, a1 as ImageProps, ao as JSX, L as LinkButtonComponent, a2 as LinkButtonProps, n as ModalComponent, a3 as ModalProps, R as RadioSelectComponent, S as SectionComponent, o as SelectComponent, p as SelectOptionComponent, a4 as SelectOptionProps, a5 as SelectProps, ai as TableComponent, ah as TableProps, T as TextComponent, q as TextInputComponent, a6 as TextInputProps, a7 as TextProps, aj as isCardLinkProps, h as isJSX, ak as jsx, am as jsxDEV, al as jsxs, t as toCardElement, k as toModalElement } from './jsx-runtime-C2ATKxHQ.js';
+export { A as ActionsComponent, B as ButtonComponent, V as ButtonProps, c as CardComponent, W as CardJSXElement, X as CardJSXProps, e as CardLinkComponent, Y as CardLinkProps, Z as CardProps, C as ChatElement, _ as ContainerProps, D as DividerComponent, $ as DividerProps, F as FieldComponent, a0 as FieldProps, f as FieldsComponent, an as Fragment, I as ImageComponent, a1 as ImageProps, ao as JSX, L as LinkButtonComponent, a2 as LinkButtonProps, n as ModalComponent, a3 as ModalProps, R as RadioSelectComponent, S as SectionComponent, o as SelectComponent, p as SelectOptionComponent, a4 as SelectOptionProps, a5 as SelectProps, ai as TableComponent, ah as TableProps, T as TextComponent, q as TextInputComponent, a6 as TextInputProps, a7 as TextProps, aj as isCardLinkProps, h as isJSX, ak as jsx, am as jsxDEV, al as jsxs, t as toCardElement, k as toModalElement } from './jsx-runtime-DraWieqP.js';

package/docs/api/chat.mdx

@@ -465,6 +465,8 @@ await bot.initialize();
 await bot.shutdown();
 ```
 
+During shutdown, the SDK calls the optional `disconnect()` method on each adapter before disconnecting the state adapter. This lets adapters clean up platform connections, close WebSockets, or tear down subscriptions. If any adapter's `disconnect()` fails, the remaining adapters and state adapter still disconnect gracefully.
+
 ### reviver
 
 Get a `JSON.parse` reviver that deserializes `Thread` and `Message` objects from workflow payloads.

package/docs/api/index.mdx

@@ -24,7 +24,7 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 
 | Export | Description |
 |--------|-------------|
-| [`toAiMessages`](/docs/streaming#toaimessagesmessages-options) | Convert `Message[]` to AI SDK `{ role, content }[]` format |
+| [`toAiMessages`](/docs/api/to-ai-messages) | Convert `Message[]` to AI SDK `{ role, content }[]` format |
 
 ## Message formats
 

package/docs/api/message.mdx

@@ -186,7 +186,7 @@ Links found in incoming messages are extracted and exposed as `LinkPreview` obje
 />
 
 <Callout type="info">
-When using [`toAiMessages()`](/docs/streaming#toaimessagesmessages-options), link metadata is automatically appended to the message content. Embedded message links are labeled as `[Embedded message: ...]` so the AI model understands the context.
+When using [`toAiMessages()`](/docs/api/to-ai-messages), link metadata is automatically appended to the message content. Embedded message links are labeled as `[Embedded message: ...]` so the AI model understands the context.
 </Callout>
 
 ### Platform support

package/docs/api/postable-message.mdx

@@ -150,7 +150,7 @@ await thread.post(result.fullStream);
 await thread.post(result.textStream);
 ```
 
-When using `fullStream`, the SDK auto-detects `text-delta` and `step-finish` events, extracting text and inserting paragraph breaks between agent steps.
+When using `fullStream`, the SDK auto-detects `text-delta` and `finish-step` events, extracting text and inserting paragraph breaks between agent steps.
 
 ## FileUpload
 

package/docs/api/to-ai-messages.mdx

@@ -0,0 +1,190 @@
+---
+title: toAiMessages
+description: Convert Chat SDK messages to AI SDK conversation format.
+type: reference
+---
+
+Convert an array of `Message` objects into the `{ role, content }[]` format expected by AI SDKs. The output is structurally compatible with AI SDK's `ModelMessage[]`.
+
+```typescript
+import { toAiMessages } from "chat";
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { toAiMessages } from "chat";
+
+bot.onSubscribedMessage(async (thread, message) => {
+  const result = await thread.adapter.fetchMessages(thread.id, { limit: 20 });
+  const history = await toAiMessages(result.messages);
+  const response = await agent.stream({ prompt: history });
+  await thread.post(response.fullStream);
+});
+```
+
+## Signature
+
+```typescript
+function toAiMessages(
+  messages: Message[],
+  options?: ToAiMessagesOptions
+): Promise<AiMessage[]>
+```
+
+### Parameters
+
+<TypeTable
+  type={{
+    messages: {
+      description: 'Array of Chat SDK Message objects. Works with FetchResult.messages, thread.recentMessages, or any collected iterable.',
+      type: 'Message[]',
+    },
+    options: {
+      description: 'Optional configuration.',
+      type: 'ToAiMessagesOptions',
+      default: '{}',
+    },
+  }}
+/>
+
+### Options
+
+<TypeTable
+  type={{
+    includeNames: {
+      description: 'Prefix user messages with [username]: for multi-user context.',
+      type: 'boolean',
+      default: 'false',
+    },
+    transformMessage: {
+      description: 'Transform or filter each message after default processing. Return null to skip the message.',
+      type: '(aiMessage: AiMessage, source: Message) => AiMessage | null | Promise<AiMessage | null>',
+    },
+    onUnsupportedAttachment: {
+      description: 'Called when an attachment type is not supported (video, audio).',
+      type: '(attachment: Attachment, message: Message) => void',
+      default: 'console.warn',
+    },
+  }}
+/>
+
+### Returns
+
+`Promise<AiMessage[]>` — an array of messages with `role` and `content` fields, directly assignable to AI SDK's `ModelMessage[]`.
+
+## Behavior
+
+- **Role mapping** — `author.isMe === true` maps to `"assistant"`, all others to `"user"`
+- **Filtering** — Messages with empty or whitespace-only text are removed
+- **Sorting** — Messages are sorted chronologically (oldest first) by `metadata.dateSent`
+- **Links** — Link metadata (URL, title, description, site name) is appended to message content. Embedded message links are labeled as `[Embedded message: ...]`
+- **Attachments** — Images and text files (JSON, XML, YAML, etc.) are included as multipart content using `fetchData()`. Video and audio attachments trigger `onUnsupportedAttachment`
+
+## Return types
+
+```typescript
+type AiMessage = AiUserMessage | AiAssistantMessage;
+
+interface AiUserMessage {
+  role: "user";
+  content: string | AiMessagePart[];
+}
+
+interface AiAssistantMessage {
+  role: "assistant";
+  content: string;
+}
+```
+
+User messages have multipart `content` when attachments are present:
+
+```typescript
+type AiMessagePart = AiTextPart | AiImagePart | AiFilePart;
+
+interface AiTextPart {
+  type: "text";
+  text: string;
+}
+
+interface AiImagePart {
+  type: "image";
+  image: DataContent | URL;
+  mediaType?: string;
+}
+
+interface AiFilePart {
+  type: "file";
+  data: DataContent | URL;
+  filename?: string;
+  mediaType: string;
+}
+```
+
+## Examples
+
+### Multi-user context
+
+Prefix each user message with their username so the AI model can distinguish speakers:
+
+```typescript
+const history = await toAiMessages(result.messages, { includeNames: true });
+// [{ role: "user", content: "[alice]: Hello" },
+//  { role: "assistant", content: "Hi there!" },
+//  { role: "user", content: "[bob]: Thanks" }]
+```
+
+### Transforming messages
+
+Replace raw user IDs with readable names:
+
+```typescript
+const history = await toAiMessages(result.messages, {
+  transformMessage: (aiMessage) => {
+    if (typeof aiMessage.content === "string") {
+      return {
+        ...aiMessage,
+        content: aiMessage.content.replace(/<@U123>/g, "@VercelBot"),
+      };
+    }
+    return aiMessage;
+  },
+});
+```
+
+### Filtering messages
+
+Skip messages from a specific user:
+
+```typescript
+const history = await toAiMessages(result.messages, {
+  transformMessage: (aiMessage, source) => {
+    if (source.author.userId === "U_NOISY_BOT") return null;
+    return aiMessage;
+  },
+});
+```
+
+### Handling unsupported attachments
+
+```typescript
+const history = await toAiMessages(result.messages, {
+  onUnsupportedAttachment: (attachment, message) => {
+    logger.warn(`Skipped ${attachment.type} attachment in message ${message.id}`);
+  },
+});
+```
+
+## Supported attachment types
+
+| Type | MIME types | Included as |
+|------|-----------|-------------|
+| `image` | Any image MIME type | `FilePart` with base64 data |
+| `file` | `text/*`, `application/json`, `application/xml`, `application/javascript`, `application/typescript`, `application/yaml`, `application/toml` | `FilePart` with base64 data |
+| `video` | Any | Skipped (triggers `onUnsupportedAttachment`) |
+| `audio` | Any | Skipped (triggers `onUnsupportedAttachment`) |
+| `file` | Other (e.g. `application/pdf`) | Silently skipped |
+
+<Callout type="info">
+Attachments require `fetchData()` to be available on the attachment object. Attachments without `fetchData()` are silently skipped.
+</Callout>

package/docs/concurrency.mdx

@@ -0,0 +1,223 @@
+---
+title: Concurrency
+description: Control how overlapping messages on the same thread are handled — queue, debounce, drop, or process concurrently.
+type: guide
+prerequisites:
+  - /docs/handling-events
+related:
+  - /docs/state
+  - /docs/streaming
+---
+
+When multiple messages arrive on the same thread while a handler is still processing, the SDK needs a strategy. By default, the incoming message is dropped. The `concurrency` option on `ChatConfig` lets you choose what happens instead.
+
+## Strategies
+
+### Drop (default)
+
+The original behavior. If a handler is already running on a thread, the new message is discarded and a `LockError` is thrown. No queuing, no retries.
+
+```typescript title="lib/bot.ts"
+const bot = new Chat({
+  concurrency: "drop",
+  // ...
+});
+```
+
+### Queue
+
+Messages that arrive while a handler is running are enqueued. When the current handler finishes, only the **latest** queued message is dispatched. All intermediate messages are provided as `context.skipped`, giving your handler full visibility into what happened while it was busy.
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  concurrency: "queue",
+  // ...
+});
+
+bot.onNewMention(async (thread, message, context) => {
+  if (context && context.skipped.length > 0) {
+    await thread.post(
+      `You sent ${context.totalSinceLastHandler} messages while I was thinking. Responding to your latest.`
+    );
+  }
+
+  const response = await generateAIResponse(message.text);
+  await thread.post(response);
+});
+```
+
+**Flow:**
+
+```
+A arrives  → acquire lock → process A
+B arrives  → lock busy → enqueue B
+C arrives  → lock busy → enqueue C
+D arrives  → lock busy → enqueue D
+A done     → drain: [B, C, D] → handler(D, { skipped: [B, C] })
+D done     → queue empty → release lock
+```
+
+### Debounce
+
+Every message starts or resets a debounce timer. Only the **final message in a burst** is processed.
+
+This is particularly useful for platforms like **WhatsApp** and **Telegram** where users tend to send a flurry of short messages in quick succession instead of composing a single message — "hey", "quick question", "how do I reset my password?" arriving as three separate webhooks within a few seconds. Without debounce, the bot would respond to "hey" before the actual question even arrives. With debounce, the SDK waits for a pause in the conversation and processes only the final message.
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  concurrency: { strategy: "debounce", debounceMs: 1500 },
+  // ...
+});
+```
+
+<Callout type="info">
+WhatsApp and Telegram adapters default to `lockScope: "channel"`, so debounce applies to the entire conversation — not just a single thread.
+</Callout>
+
+**Flow:**
+
+```
+A arrives  → acquire lock → store A as pending → sleep(debounceMs)
+B arrives  → lock busy → overwrite pending with B (A dropped)
+C arrives  → lock busy → overwrite pending with C (B dropped)
+             ... debounceMs elapses with no new message ...
+           → process C → release lock
+```
+
+Debounce also works well for rapid corrections ("wait, I meant...") and multi-part messages on any platform.
+
+### Concurrent
+
+No locking at all. Every message is processed immediately in its own handler invocation. Use this for stateless handlers where thread ordering doesn't matter.
+
+```typescript title="lib/bot.ts"
+const bot = new Chat({
+  concurrency: "concurrent",
+  // ...
+});
+```
+
+## Configuration
+
+For fine-grained control, pass a `ConcurrencyConfig` object instead of a strategy string:
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  concurrency: {
+    strategy: "queue",
+    maxQueueSize: 20,          // Max queued messages per thread (default: 10)
+    onQueueFull: "drop-oldest", // or "drop-newest" (default: "drop-oldest")
+    queueEntryTtlMs: 60_000,  // Discard stale entries after 60s (default: 90s)
+  },
+  // ...
+});
+```
+
+### All options
+
+| Option | Strategies | Default | Description |
+|--------|-----------|---------|-------------|
+| `strategy` | all | `"drop"` | The concurrency strategy to use |
+| `maxQueueSize` | queue, debounce | `10` | Maximum queued messages per thread |
+| `onQueueFull` | queue, debounce | `"drop-oldest"` | Whether to evict the oldest or reject the newest message when the queue is full |
+| `queueEntryTtlMs` | queue, debounce | `90000` | TTL for queued entries in milliseconds. Expired entries are discarded on dequeue |
+| `debounceMs` | debounce | `1500` | Debounce window in milliseconds |
+| `maxConcurrent` | concurrent | `Infinity` | Max concurrent handlers per thread |
+
+## MessageContext
+
+All handler types (`onNewMention`, `onSubscribedMessage`, `onNewMessage`) accept an optional `MessageContext` as their last parameter. It is only populated when using the `queue` strategy and messages were skipped.
+
+```typescript
+interface MessageContext {
+  /** Messages that arrived while the previous handler was running, in chronological order. */
+  skipped: Message[];
+  /** Total messages received since last handler ran (skipped.length + 1). */
+  totalSinceLastHandler: number;
+}
+```
+
+Existing handlers that don't use `context` are unaffected — the parameter is optional.
+
+### Example: Pass all messages to an LLM
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, message, context) => {
+  // Combine skipped messages with the current one for full context
+  const allMessages = [...(context?.skipped ?? []), message];
+
+  const response = await generateAIResponse(
+    allMessages.map((m) => m.text).join("\n\n")
+  );
+  await thread.post(response);
+});
+```
+
+## Lock scope
+
+By default, locks are scoped to the thread — messages in different threads are processed independently. For platforms like WhatsApp and Telegram where conversations happen at the channel level rather than in threads, the lock scope defaults to `"channel"`.
+
+You can override this globally:
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  concurrency: "queue",
+  lockScope: "channel", // or "thread" (default)
+  // ...
+});
+```
+
+Or resolve it dynamically per message:
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  concurrency: "queue",
+  lockScope: ({ isDM, adapter }) => {
+    // Use channel scope for DMs, thread scope for group channels
+    return isDM ? "channel" : "thread";
+  },
+  // ...
+});
+```
+
+## State adapter requirements
+
+The `queue` and `debounce` strategies require three additional methods on your state adapter:
+
+| Method | Description |
+|--------|-------------|
+| `enqueue(threadId, entry, maxSize)` | Atomically append a message to the thread's queue. Returns new depth. |
+| `dequeue(threadId)` | Pop the next (oldest) message from the queue. Returns `null` if empty. |
+| `queueDepth(threadId)` | Return the current number of queued messages. |
+
+All built-in state adapters (`@chat-adapter/state-memory`, `@chat-adapter/state-redis`, `@chat-adapter/state-ioredis`) implement these methods. The Redis adapters use Lua scripts for atomicity.
+
+## Observability
+
+All strategies emit structured log events at `info` level:
+
+| Event | Strategy | Data |
+|-------|----------|------|
+| `message-queued` | queue | threadId, messageId, queueDepth |
+| `message-dequeued` | queue, debounce | threadId, messageId, skippedCount |
+| `message-dropped` | drop, queue | threadId, messageId, reason |
+| `message-expired` | queue, debounce | threadId, messageId |
+| `message-superseded` | debounce | threadId, droppedId |
+| `message-debouncing` | debounce | threadId, messageId, debounceMs |
+| `message-debounce-reset` | debounce | threadId, messageId |
+
+## Choosing a strategy
+
+| Use case | Strategy | Why |
+|----------|----------|-----|
+| Simple bots, one-shot commands | `drop` | No complexity, no queue overhead |
+| AI chatbots, customer support | `queue` | Never lose messages; handler sees full conversation context |
+| WhatsApp/Telegram bots, rapid corrections | `debounce` | Users send many short messages in quick succession; wait for a pause before responding |
+| Stateless lookups, translations | `concurrent` | Maximum throughput, no ordering needed |
+
+## Backward compatibility
+
+- The default strategy is `drop` — existing behavior is unchanged.
+- The deprecated `onLockConflict` option continues to work but should be replaced with `concurrency`.
+- Handler signatures are backward-compatible; the new `context` parameter is optional.
+- Deduplication always runs regardless of strategy.

package/docs/contributing/building.mdx

@@ -31,7 +31,7 @@ Chat SDK ships with Vercel-maintained adapters for Slack, Teams, Google Chat, Di
 
 #### Qualifications for vendor official tier
 
-- Committment for continued maintenance of the adapter.
+- Commitment for continued maintenance of the adapter.
 - GitHub hosting in official vendor-owned org.
 - Documentation of the adapter in primary vendor docs.
 - Announcement of the adapter in blog post or changelog and social media.
@@ -241,6 +241,19 @@ async initialize(chat: ChatInstance): Promise<void> {
 }
 ```
 
+### Disconnect
+
+The optional `disconnect()` method is called during `chat.shutdown()` to clean up resources. Use it to close persistent connections, tear down subscriptions, or release any platform-specific resources.
+
+```typescript title="src/adapter.ts"
+async disconnect(): Promise<void> {
+  // Close WebSocket connections, clean up subscriptions, etc.
+  // Example: await this.matrixClient.stop();
+}
+```
+
+Adapters that don't hold persistent connections can skip this method entirely.
+
 ### Thread ID encode/decode
 
 Thread IDs typically follow the pattern `{adapter}:{segment1}:{segment2}`, though some adapters use more or fewer segments. The `encodeThreadId` and `decodeThreadId` methods must roundtrip consistently. Use `base64url` encoding for segments that contain special characters.
@@ -530,6 +543,7 @@ These methods are not required but extend your adapter's capabilities:
 
 | Method | Purpose |
 |--------|---------|
+| `disconnect()` | Clean up connections and resources during shutdown |
 | `openDM(userId)` | Open a direct message conversation |
 | `isDM(threadId)` | Check if a thread is a DM |
 | `stream(threadId, textStream)` | Stream AI responses in real-time |

package/docs/guides/code-review-hono.mdx

@@ -23,7 +23,7 @@ Scaffold a new Hono project and install dependencies:
 ```sh title="Terminal"
 pnpm create hono my-review-bot
 cd my-review-bot
-pnpm add @octokit/rest @vercel/sandbox ai bash-tool chat @chat-adapter/github @chat-adapter/state-redis
+pnpm add @octokit/rest @vercel/functions @vercel/sandbox ai bash-tool chat @chat-adapter/github @chat-adapter/state-redis
 ```
 
 <Callout type="info">
@@ -198,6 +198,7 @@ Create the Hono app with a single webhook route that delegates to Chat SDK:
 
 ```typescript title="src/index.ts" lineNumbers
 import { Hono } from "hono";
+import { waitUntil } from "@vercel/functions";
 import { bot } from "./bot";
 
 const app = new Hono();
@@ -208,15 +209,13 @@ app.post("/api/webhooks/github", async (c) => {
     return c.text("GitHub adapter not configured", 404);
   }
 
-  return handler(c.req.raw, {
-    waitUntil: (task) => c.executionCtx.waitUntil(task),
-  });
+  return handler(c.req.raw, { waitUntil });
 });
 
 export default app;
 ```
 
-Chat SDK's GitHub adapter handles signature verification, event parsing, and routing internally. The `waitUntil` option ensures the review completes after the HTTP response is sent.
+Chat SDK's GitHub adapter handles signature verification, event parsing, and routing internally. The `waitUntil` option ensures the review completes after the HTTP response is sent — required on serverless platforms where the function would otherwise terminate before your handlers finish.
 
 ## Test locally
 

package/docs/handling-events.mdx

@@ -111,6 +111,8 @@ bot.onSubscribedMessage(async (thread, message) => {
 });
 ```
 
+See [`toAiMessages`](/docs/api/to-ai-messages) for all options including multi-user name prefixing, message transforms, and attachment handling.
+
 ### Example: Unsubscribe on keyword
 
 ```typescript title="lib/bot.ts" lineNumbers

package/docs/meta.json

@@ -12,6 +12,7 @@
     "adapters",
     "state",
     "---Features---",
+    "concurrency",
     "...",
     "error-handling",
     "---Guides---",

package/docs/posting-messages.mdx

@@ -151,6 +151,8 @@ await thread.post(result.fullStream);
 
 Both `fullStream` and `textStream` are supported. Use `fullStream` with multi-step agents — it preserves paragraph breaks between steps. Any `AsyncIterable<string>` also works for custom streams.
 
+For multi-turn conversations, use [`toAiMessages()`](/docs/api/to-ai-messages) to convert thread history into the `{ role, content }[]` format expected by AI SDKs.
+
 See the [Streaming](/docs/streaming) page for details on platform behavior and configuration.
 
 ## Attachments and files

package/docs/streaming.mdx

@@ -28,7 +28,7 @@ bot.onNewMention(async (thread, message) => {
 
 ### Why `fullStream` over `textStream`?
 
-When AI SDK agents make tool calls between text steps, `textStream` concatenates all text without separators — `"hello.how are you?"` instead of `"hello.\n\nhow are you?"`. The `fullStream` contains explicit `step-finish` events that Chat SDK uses to inject paragraph breaks between steps automatically.
+When AI SDK agents make tool calls between text steps, `textStream` concatenates all text without separators — `"hello.how are you?"` instead of `"hello.\n\nhow are you?"`. The `fullStream` contains explicit `finish-step` events that Chat SDK uses to inject paragraph breaks between steps automatically.
 
 Both stream types are auto-detected:
 
@@ -184,7 +184,7 @@ await thread.stream(textStream, {
 ## Streaming with conversation history
 
 Combine message history with streaming for multi-turn AI conversations.
-Use `toAiMessages()` to convert chat messages into the `{ role, content }` format expected by AI SDKs:
+Use [`toAiMessages()`](/docs/api/to-ai-messages) to convert chat messages into the `{ role, content }` format expected by AI SDKs:
 
 ```typescript title="lib/bot.ts" lineNumbers
 import { toAiMessages } from "chat";
@@ -200,51 +200,4 @@ bot.onSubscribedMessage(async (thread, message) => {
 });
 ```
 
-### `toAiMessages(messages, options?)`
-
-Converts an array of `Message` objects into AI SDK conversation format:
-
-- Maps `author.isMe` to `"assistant"` role, all others to `"user"`
-- Filters out empty messages
-- Sorts chronologically (oldest first)
-- Appends link metadata (URLs, titles, descriptions) when present
-- Labels embedded message links (e.g. shared Slack messages) as `[Embedded message: ...]`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `includeNames` | `boolean` | `false` | Prefix user messages with `[username]: ` for multi-user context |
-| `transformMessage` | `(aiMessage, source) => AiMessage \| Promise<AiMessage \| null> \| null` | — | Transform or filter each message after default processing. Return `null` to skip. |
-| `onUnsupportedAttachment` | `(attachment, message) => void` | `console.warn` | Called when an attachment type is not supported |
-
-### Customizing messages with `transformMessage`
-
-Use `transformMessage` to modify, enrich, or filter messages after default processing:
-
-```typescript title="lib/bot.ts" lineNumbers
-import { toAiMessages } from "chat";
-
-const history = await toAiMessages(result.messages, {
-  transformMessage: (aiMessage, source) => {
-    // Replace bot user IDs with readable names
-    if (typeof aiMessage.content === "string") {
-      return {
-        ...aiMessage,
-        content: aiMessage.content.replace(/<@U123>/g, "@VercelBot"),
-      };
-    }
-    return aiMessage;
-  },
-});
-```
-
-Return `null` to skip a message entirely:
-
-```typescript
-const history = await toAiMessages(result.messages, {
-  transformMessage: (aiMessage, source) => {
-    // Skip messages from a specific user
-    if (source.author.userId === "U_NOISY_BOT") return null;
-    return aiMessage;
-  },
-});
-```
+See the [`toAiMessages` API reference](/docs/api/to-ai-messages) for all options including `includeNames`, `transformMessage`, and attachment handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.20.2",
+  "version": "4.22.0",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",