chat 4.28.1 → 4.29.0

package/dist/index.js

@@ -61,131 +61,9 @@ import {
   toPlainText,
   walkAst
 } from "./chunk-V25FKIIL.js";
-
-// src/ai.ts
-var TEXT_MIME_PREFIXES = [
-  "text/",
-  "application/json",
-  "application/xml",
-  "application/javascript",
-  "application/typescript",
-  "application/yaml",
-  "application/x-yaml",
-  "application/toml"
-];
-function isTextMimeType(mimeType) {
-  return TEXT_MIME_PREFIXES.some(
-    (prefix) => mimeType === prefix || mimeType.startsWith(prefix)
-  );
-}
-async function attachmentToPart(att) {
-  if (att.type === "image") {
-    if (att.fetchData) {
-      try {
-        const buffer = await att.fetchData();
-        const mimeType = att.mimeType ?? "image/png";
-        return {
-          type: "file",
-          data: `data:${mimeType};base64,${buffer.toString("base64")}`,
-          mediaType: mimeType,
-          filename: att.name
-        };
-      } catch (error) {
-        console.error("toAiMessages: failed to fetch image data", error);
-        return null;
-      }
-    }
-    return null;
-  }
-  if (att.type === "file" && att.mimeType && isTextMimeType(att.mimeType)) {
-    if (att.fetchData) {
-      try {
-        const buffer = await att.fetchData();
-        return {
-          type: "file",
-          data: `data:${att.mimeType};base64,${buffer.toString("base64")}`,
-          filename: att.name,
-          mediaType: att.mimeType
-        };
-      } catch (error) {
-        console.error("toAiMessages: failed to fetch file data", error);
-        return null;
-      }
-    }
-    return null;
-  }
-  return null;
-}
-async function toAiMessages(messages, options) {
-  const includeNames = options?.includeNames ?? false;
-  const transformMessage = options?.transformMessage;
-  const onUnsupported = options?.onUnsupportedAttachment ?? ((att) => {
-    console.warn(
-      `toAiMessages: unsupported attachment type "${att.type}"${att.name ? ` (${att.name})` : ""} \u2014 skipped`
-    );
-  });
-  const sorted = [...messages].sort(
-    (a, b) => (a.metadata.dateSent?.getTime() ?? 0) - (b.metadata.dateSent?.getTime() ?? 0)
-  );
-  const filtered = sorted.filter((msg) => msg.text.trim());
-  const results = await Promise.all(
-    filtered.map(async (msg) => {
-      const role = msg.author.isMe ? "assistant" : "user";
-      let textContent = includeNames && role === "user" ? `[${msg.author.userName}]: ${msg.text}` : msg.text;
-      if (msg.links && msg.links.length > 0) {
-        const linkParts = msg.links.map((link2) => {
-          const parts = link2.fetchMessage ? [`[Embedded message: ${link2.url}]`] : [link2.url];
-          if (link2.title) {
-            parts.push(`Title: ${link2.title}`);
-          }
-          if (link2.description) {
-            parts.push(`Description: ${link2.description}`);
-          }
-          if (link2.siteName) {
-            parts.push(`Site: ${link2.siteName}`);
-          }
-          return parts.join("\n");
-        }).join("\n\n");
-        textContent += `
-
-Links:
-${linkParts}`;
-      }
-      let aiMessage;
-      if (role === "user") {
-        const attachmentParts = [];
-        for (const att of msg.attachments ?? []) {
-          const part = await attachmentToPart(att);
-          if (part) {
-            attachmentParts.push(part);
-          } else if (att.type === "video" || att.type === "audio") {
-            onUnsupported(att, msg);
-          }
-        }
-        if (attachmentParts.length > 0) {
-          aiMessage = {
-            role,
-            content: [
-              { type: "text", text: textContent },
-              ...attachmentParts
-            ]
-          };
-        } else {
-          aiMessage = { role, content: textContent };
-        }
-      } else {
-        aiMessage = { role, content: textContent };
-      }
-      if (transformMessage) {
-        return { result: await transformMessage(aiMessage, msg), source: msg };
-      }
-      return { result: aiMessage, source: msg };
-    })
-  );
-  return results.filter(
-    (r) => r.result != null
-  ).map((r) => r.result);
-}
+import {
+  toAiMessages
+} from "./chunk-HD375J7S.js";
 
 // src/channel.ts
 import { WORKFLOW_DESERIALIZE as WORKFLOW_DESERIALIZE2, WORKFLOW_SERIALIZE as WORKFLOW_SERIALIZE2 } from "@workflow/serde";
@@ -2515,9 +2393,13 @@ var Chat = class {
   /**
    * Register a handler for direct messages.
    *
-   * Called when a message is received in a DM thread that is not subscribed.
-   * If no `onDirectMessage` handlers are registered, DMs fall through to
-   * `onNewMention` for backward compatibility.
+   * Called for every message received in a DM thread when at least one
+   * direct message handler is registered. Direct message handlers run before
+   * `onSubscribedMessage`, `onNewMention`, and pattern handlers.
+   *
+   * If no `onDirectMessage` handlers are registered, DMs continue through
+   * normal routing. Unsubscribed DMs fall through to `onNewMention` for
+   * backward compatibility.
    *
    * @param handler - Handler called for DM messages
    *
@@ -3534,7 +3416,7 @@ var Chat = class {
    * - Deduplication: Same message may arrive multiple times (e.g., Slack sends
    *   both `message` and `app_mention` events, GChat sends direct webhook + Pub/Sub)
    * - Bot filtering: Messages from the bot itself are skipped
-   * - Concurrency: Controlled by `concurrency` config (drop, queue, debounce, concurrent)
+   * - Concurrency: Controlled by `concurrency` config (drop, queue, debounce, burst, concurrent)
    */
   async handleIncomingMessage(adapter, threadId, message) {
     setMessageAdapter(message, adapter);
@@ -3583,7 +3465,7 @@ var Chat = class {
       await this.handleConcurrent(adapter, threadId, message);
       return;
     }
-    if (strategy === "queue" || strategy === "debounce") {
+    if (strategy === "queue" || strategy === "debounce" || strategy === "burst") {
       await this.handleQueueOrDebounce(
         adapter,
         threadId,
@@ -3702,6 +3584,25 @@ var Chat = class {
           debounceMs
         });
         await this.debounceLoop(lock, adapter, threadId, lockKey);
+      } else if (strategy === "burst") {
+        await this._stateAdapter.enqueue(
+          lockKey,
+          {
+            message,
+            enqueuedAt: Date.now(),
+            expiresAt: Date.now() + queueEntryTtlMs
+          },
+          maxQueueSize
+        );
+        this.logger.info("message-debouncing", {
+          threadId,
+          lockKey,
+          messageId: message.id,
+          debounceMs
+        });
+        await sleep(debounceMs);
+        await this._stateAdapter.extendLock(lock, DEFAULT_LOCK_TTL_MS);
+        await this.drainQueue(lock, adapter, threadId, lockKey);
       } else {
         await this.dispatchToHandlers(adapter, threadId, message);
         await this.drainQueue(lock, adapter, threadId, lockKey);

package/dist/{jsx-runtime-DxGwoLu2.d.ts → jsx-runtime-CFq1K_Ve.d.ts}

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

package/dist/jsx-runtime.d.ts

@@ -1 +1 @@
-export { A as ActionsComponent, B as ButtonComponent, X as ButtonProps, c as CardComponent, Y as CardJSXElement, Z as CardJSXProps, e as CardLinkComponent, _ as CardLinkProps, $ as CardProps, C as ChatElement, a0 as ContainerProps, D as DividerComponent, a1 as DividerProps, E as ExternalSelectComponent, a2 as ExternalSelectProps, F as FieldComponent, a3 as FieldProps, f as FieldsComponent, ar as Fragment, I as ImageComponent, a4 as ImageProps, as as JSX, L as LinkButtonComponent, a5 as LinkButtonProps, o as ModalComponent, a6 as ModalProps, R as RadioSelectComponent, j as SectionComponent, p as SelectComponent, q as SelectOptionComponent, a7 as SelectOptionProps, a8 as SelectProps, am as TableComponent, al as TableProps, T as TextComponent, r as TextInputComponent, a9 as TextInputProps, aa as TextProps, an as isCardLinkProps, h as isJSX, ao as jsx, aq as jsxDEV, ap as jsxs, t as toCardElement, l as toModalElement } from './jsx-runtime-DxGwoLu2.js';
+export { A as ActionsComponent, B as ButtonComponent, U as ButtonProps, b as CardComponent, V as CardJSXElement, W as CardJSXProps, d as CardLinkComponent, X as CardLinkProps, Y as CardProps, Z as ChatElement, _ as ContainerProps, D as DividerComponent, $ as DividerProps, E as ExternalSelectComponent, a0 as ExternalSelectProps, F as FieldComponent, a1 as FieldProps, e as FieldsComponent, ar as Fragment, I as ImageComponent, a2 as ImageProps, as as JSX, L as LinkButtonComponent, a3 as LinkButtonProps, M as ModalComponent, a4 as ModalProps, R as RadioSelectComponent, S as SectionComponent, m as SelectComponent, n as SelectOptionComponent, a5 as SelectOptionProps, a6 as SelectProps, am as TableComponent, al as TableProps, T as TextComponent, o as TextInputComponent, a7 as TextInputProps, a8 as TextProps, an as isCardLinkProps, g as isJSX, ao as jsx, aq as jsxDEV, ap as jsxs, t as toCardElement, j as toModalElement } from './jsx-runtime-CFq1K_Ve.js';

package/docs/adapters.mdx

@@ -8,12 +8,13 @@ prerequisites:
 
 Adapters handle webhook verification, message parsing, and API calls for each platform. Install only the adapters you need. Browse all available adapters — including community-built ones — on the [Adapters](/adapters) page.
 
-Need a browser chat UI? See the [Web adapter](/adapters/web) — it speaks the AI SDK `useChat` protocol so the same bot serves Slack, Teams, **and** a `<Conversation>` from `ai-elements` out of the box.
+Need a browser chat UI? See the [Web adapter](/adapters/official/web) — it speaks the AI SDK UI stream protocol and works with React (`@ai-sdk/react`), Vue (`@ai-sdk/vue`), and Svelte (`@ai-sdk/svelte`), so the same bot serves Slack, Teams, **and** any browser framework out of the box.
 
 Ready to build your own? Follow the [building](/docs/contributing/building) guide.
 
 ## Feature matrix
 
+<GlobalFeatureMatrix type="platform" />
 ### Messaging
 
 | Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/google-chat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) | [Messenger](/adapters/messenger) |
@@ -21,7 +22,7 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 | Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
 | Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
 | Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
-| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file | <Cross /> | <Cross /> | <Check /> Images, audio, docs | <Cross /> |
+| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file/media | <Cross /> | <Cross /> | <Check /> Images, audio, docs | <Cross /> |
 | Streaming | <Check /> Native | <Warn /> Native (DMs) / Buffered | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Buffered | <Warn /> Agent sessions / Post+Edit | <Warn /> Buffered | <Warn /> Buffered |
 | Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
@@ -51,7 +52,7 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 | Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 | User lookup ([`getUser`](/docs/api/chat#getuser)) | <Check /> | <Warn /> Cached | <Warn /> Cached | <Check /> | <Warn /> Seen users | <Check /> | <Check /> | <Cross /> | <Cross /> |
 | Parent subject ([`message.subject`](/docs/subject)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
-| Native client ([`.client`](/docs/api/chat#getadapter)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Native client ([`.webClient` / `.octokit` / `.linearClient`](/docs/api/chat#getadapter)) | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
 | Custom API endpoint (`apiUrl`) | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
 
 ### Message history
@@ -114,3 +115,32 @@ Each adapter auto-detects credentials from environment variables, so you only ne
 </Callout>
 
 Each adapter creates a webhook handler accessible via `bot.webhooks.<name>`.
+
+## Customizing an adapter via subclassing
+
+Each official adapter exposes its extension surface as `protected` members so you can subclass it to override or extend platform-specific behavior without forking the package. Use this when you need to handle a payload type the built-in adapter doesn't cover, intercept verification, or wrap an existing handler.
+
+```typescript title="lib/custom-telegram.ts" lineNumbers
+import { TelegramAdapter, type TelegramUpdate } from "@chat-adapter/telegram";
+import type { WebhookOptions } from "chat";
+
+export class CustomTelegramAdapter extends TelegramAdapter {
+  protected override processUpdate(
+    update: TelegramUpdate,
+    options?: WebhookOptions
+  ): void {
+    // Handle a payload type the base adapter doesn't, e.g. chat_join_request.
+    if ("chat_join_request" in update) {
+      this.logger.info("Received chat_join_request", { update });
+      return;
+    }
+    super.processUpdate(update, options);
+  }
+}
+```
+
+Construct your subclass anywhere you'd construct the base adapter — for example, `adapters: { telegram: new CustomTelegramAdapter({ ... }) }`. Members marked `private` (internal caches, in-flight runtime state, one-shot warning flags) intentionally remain inaccessible; if you find a hook you need that isn't `protected`, please open an issue.
+
+<Callout type="warn">
+  The `protected` extension surface is intentionally broader than the public API but is not yet considered fully stable. Method signatures may evolve (renames, parameter changes, new hook splits) in minor releases as we learn from real-world subclasses. Pin the adapter version you build against, watch the changelog for the affected adapter, and prefer overriding the smallest hook that solves your problem so upgrades stay easy. If you rely on a particular hook, please open an issue so we can promote it to a stable, documented extension point.
+</Callout>

package/docs/ai/ai-sdk-tools.mdx

@@ -0,0 +1,227 @@
+---
+title: AI SDK Tools
+description: Give an AI agent the ability to operate inside your workspace. Post messages, send DMs, react, edit, delete; all with built-in approval gates.
+type: guide
+prerequisites:
+  - /docs/usage
+related:
+  - /docs/ai
+  - /docs/ai/to-ai-messages
+  - /docs/streaming
+  - /docs/conversation-history
+---
+
+`createChatTools` exposes Chat SDK operations as ready-to-use [AI SDK](https://ai-sdk.dev) tools so an agent can act inside the same workspaces your bot is connected to: read messages, post replies, send DMs, react, edit, delete, and manage thread subscriptions across every adapter you've registered.
+
+Write operations require user approval out of the box, toggle them globally or per-tool when you want unattended execution.
+
+## Installation
+
+The tools live in the [`chat/ai`](/docs/ai) subpath of the core `chat` package:
+
+```ts
+import { createChatTools } from "chat/ai";
+```
+
+`ai` and `zod` are optional peer dependencies — install them if you haven't already:
+
+<PackageInstall package="ai zod" />
+
+<Callout>
+  Pair `createChatTools` with [`toAiMessages`](/docs/ai/to-ai-messages)
+  to feed prior thread history into the agent before it picks a tool.
+  Both ship from the same `chat/ai` subpath, which keeps the optional
+  `ai` / `zod` peer deps out of bundles that don't import them.
+</Callout>
+
+## Quick start
+
+Pass your `Chat` instance and the tools you want into any AI SDK call:
+
+```typescript title="lib/agent.ts" lineNumbers
+import { Chat } from "chat";
+import { createChatTools } from "chat/ai";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createMemoryState } from "@chat-adapter/state-memory";
+import { generateText } from "ai";
+
+const chat = new Chat({
+  userName: "mybot",
+  adapters: { slack: createSlackAdapter() },
+  state: createMemoryState(),
+});
+
+const result = await generateText({
+  model: "anthropic/claude-sonnet-4.6",
+  tools: createChatTools({
+    chat,
+    preset: "messenger",
+    requireApproval: false, // unattended script, no human-in-the-loop needed
+  }),
+  prompt:
+    "Post a friendly hello in slack:C0123ABC and react to it with a thumbs up.",
+});
+```
+
+Each tool resolves the right adapter from the id prefix you give it (`slack:...`, `discord:...`, `gchat:...`), so the same agent can drive any platform your `Chat` instance is wired up to.
+
+## Presets
+
+Pass `preset` to scope the toolset down to what an agent actually needs.
+
+```typescript
+// Read-only — fetch messages, threads, channel info, users
+createChatTools({ chat, preset: "reader" });
+
+// Basic posting — read + post + DM + react + typing indicator
+createChatTools({ chat, preset: "messenger" });
+
+// Full management — everything including edit, delete, subscriptions
+createChatTools({ chat, preset: "moderator" });
+```
+
+Presets compose — pass an array to combine them:
+
+```typescript
+createChatTools({ chat, preset: ["reader", "messenger"] });
+```
+
+Omit `preset` entirely to get every tool (same as `'moderator'`).
+
+| Preset | Tools included |
+|---|---|
+| `reader` | `fetchMessages`, `fetchChannelMessages`, `fetchThread`, `listThreads`, `getThreadParticipants`, `getChannelInfo`, `getUser` |
+| `messenger` | `fetchMessages`, `fetchThread`, `getChannelInfo`, `getUser`, `postMessage`, `postChannelMessage`, `sendDirectMessage`, `addReaction`, `removeReaction`, `startTyping` |
+| `moderator` | All read tools plus `postMessage`, `postChannelMessage`, `sendDirectMessage`, `editMessage`, `deleteMessage`, `addReaction`, `removeReaction`, `subscribeThread`, `unsubscribeThread`, `startTyping` |
+
+## Approval control
+
+Write operations (posting, editing, deleting, reacting, subscribing) default to `needsApproval: true`. The AI SDK pauses execution and surfaces an approval request that your application is expected to confirm before the tool runs. This keeps a human in the loop for anything visible to the workspace.
+
+```typescript
+// All writes need approval (default)
+createChatTools({ chat });
+
+// No approval needed
+createChatTools({ chat, requireApproval: false });
+
+// Per-tool — only destructive actions need approval
+createChatTools({
+  chat,
+  requireApproval: {
+    deleteMessage: true,
+    editMessage: true,
+    sendDirectMessage: false,
+    postMessage: false,
+    addReaction: false,
+  },
+});
+```
+
+Read tools (`fetchMessages`, `fetchThread`, `getChannelInfo`, …) and the `startTyping` indicator never require approval.
+
+## Cherry-picking tools
+
+Each tool is also exported as a standalone factory you can hand to `tools` directly:
+
+```typescript title="lib/agent.ts" lineNumbers
+import { fetchMessages, postMessage, addReaction } from "chat/ai";
+
+const tools = {
+  fetchMessages: fetchMessages(chat),
+  postMessage: postMessage(chat, { needsApproval: false }),
+  addReaction: addReaction(chat, { needsApproval: false }),
+};
+```
+
+Useful when you want a small, targeted toolset without going through `createChatTools`.
+
+## Tool overrides
+
+Customize any AI SDK [`tool()`](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling) property per tool, keyed by tool name:
+
+```typescript
+import type { ChatToolName, ToolOverrides } from "chat/ai";
+
+createChatTools({
+  chat,
+  overrides: {
+    postMessage: {
+      description: "Reply in the active customer support thread.",
+      needsApproval: false,
+    },
+    deleteMessage: { needsApproval: true },
+  },
+});
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `description` | `string` | Custom tool description shown to the model |
+| `title` | `string` | Human-readable title |
+| `strict` | `boolean` | Strict mode for input generation |
+| `inputExamples` | `array` | Examples that show the model what tool input should look like |
+| `metadata` | `object` | Tool metadata propagated to tool call and result parts |
+| `needsApproval` | `boolean \| function` | Gate execution behind an approval request |
+| `providerOptions` | `ProviderOptions` | Provider-specific metadata |
+| `onInputStart` | `function` | Callback when argument streaming starts |
+| `onInputDelta` | `function` | Callback on each streaming delta |
+| `onInputAvailable` | `function` | Callback when full input is available |
+| `toModelOutput` | `function` | Custom mapping of tool result to model output |
+
+Core properties (`execute`, `inputSchema`, `outputSchema`, and tool-kind fields like `type`, `id`, `args`) cannot be overridden so tool semantics stay stable.
+
+## Available tools
+
+All ids accept the full Chat SDK form: `slack:C123ABC:1234567890.123456` for a thread, `slack:C123ABC` for a channel, and the platform-native user id (e.g. `U123456` on Slack, `users/123` on Google Chat). The tools auto-detect the adapter from the prefix.
+
+### Reading
+
+| Tool | Description |
+|---|---|
+| `fetchMessages` | Fetch recent messages from a thread (paginated) |
+| `fetchChannelMessages` | Fetch top-level messages in a channel (not thread replies) |
+| `fetchThread` | Fetch metadata for a thread (channel id, visibility, DM status) |
+| `listThreads` | List recent threads in a channel with their root message |
+| `getThreadParticipants` | Return the unique non-bot participants in a thread |
+| `getChannelInfo` | Fetch channel metadata (name, member count, visibility) |
+| `getUser` | Look up a user's profile by id |
+
+### Writing
+
+| Tool | Description | Default approval |
+|---|---|---|
+| `postMessage` | Post a reply in an existing thread | required |
+| `postChannelMessage` | Post a top-level message in a channel | required |
+| `sendDirectMessage` | Open a DM with a user and post in it | required |
+| `editMessage` | Edit a message the bot previously posted | required |
+| `deleteMessage` | Delete a message the bot previously posted | required |
+| `addReaction` | Add an emoji reaction to a message | required |
+| `removeReaction` | Remove a previously-added reaction | required |
+| `subscribeThread` | Subscribe the bot to all future messages in a thread | required |
+| `unsubscribeThread` | Stop receiving non-mention messages in a thread | required |
+| `startTyping` | Show a typing indicator in a thread | not gated |
+
+## API
+
+### `createChatTools(options)`
+
+Returns an object of tools, ready to spread into `tools` of any AI SDK call.
+
+```typescript
+type ChatToolsOptions = {
+  chat: Chat;
+  requireApproval?: boolean | Partial<Record<ChatWriteToolName, boolean>>;
+  preset?: ChatToolPreset | ChatToolPreset[];
+  overrides?: Partial<Record<ChatToolName, ToolOverrides>>;
+};
+
+type ChatToolPreset = "reader" | "messenger" | "moderator";
+```
+
+| Option | Description |
+|---|---|
+| `chat` | The `Chat` instance the tools dispatch operations against. Required. |
+| `preset` | Preset (or array of presets) restricting which tools are returned. Omit to get every tool. |
+| `requireApproval` | `true` (default), `false`, or per-tool overrides. Read tools and `startTyping` are never gated. |
+| `overrides` | Per-tool customization of any AI SDK `tool()` property except `execute`, `inputSchema`, and `outputSchema`. |

package/docs/ai/index.mdx

@@ -0,0 +1,63 @@
+---
+title: Overview
+description: AI utilities that ship with Chat SDK — agent tools, message conversion, and supporting types.
+type: overview
+---
+
+The `chat/ai` subpath is the home for AI utilities that ship with Chat SDK.
+
+```ts
+import { createChatTools, toAiMessages } from "chat/ai";
+```
+
+Add the optional peers if you don't already have them:
+
+<PackageInstall package="ai zod" />
+
+## What's included
+
+| Page | What it gives you |
+|---|---|
+| [AI SDK Tools](/docs/ai/ai-sdk-tools) | `createChatTools` and standalone tool factories that let an agent post messages, send DMs, react, edit, delete, and manage subscriptions across every adapter your `Chat` instance has registered. Built-in approval gates and presets keep writes safe. |
+| [`toAiMessages`](/docs/ai/to-ai-messages) | Convert Chat SDK [`Message[]`](/docs/api/message) into the `{ role, content }[]` shape expected by AI SDK calls. Handles role mapping, attachments, links, sorting, and optional per-message transforms. |
+| [Types](/docs/ai/types) | Reference for every type exported from `chat/ai` — agent message shapes, tool option contracts, presets, approval config, and the binding type that ties tools to your `Chat` instance. |
+
+## Typical flow
+
+A Chat SDK bot wired to a tool-calling agent usually looks like this:
+
+```typescript title="lib/agent.ts" lineNumbers
+import { Chat } from "chat";
+import { createChatTools, toAiMessages } from "chat/ai";
+import { ToolLoopAgent } from "ai";
+
+const chat = new Chat({ /* adapters, state, ... */ });
+
+const agent = new ToolLoopAgent({
+  model: "anthropic/claude-sonnet-4.6",
+  instructions: "You operate inside a chat workspace via Chat SDK tools.",
+  tools: createChatTools({ chat, preset: "messenger", requireApproval: true }),
+});
+
+bot.onSubscribedMessage(async (thread) => {
+  const { messages } = await thread.adapter.fetchMessages(thread.id, {
+    limit: 20,
+  });
+  const history = await toAiMessages(messages);
+  const result = await agent.stream({ prompt: history });
+  await thread.post(result.fullStream);
+});
+```
+
+1. [`toAiMessages`](/docs/ai/to-ai-messages) converts messages into an output compatible with AI SDK's `ModelMessage[]`.
+2. [`createChatTools`](/docs/ai/ai-sdk-tools) gives the agent pre-built and fully customizable AI SDK tools.
+3. The streamed response is rendered back into the thread via the standard [`thread.post(stream)`](/docs/streaming) flow.
+
+## Backwards compatibility
+
+`toAiMessages` and the related `Ai*` types are still re-exported from the top-level `chat` package so older bots keep working. Those re-exports are now flagged with `@deprecated` JSDoc — your editor will surface a hint pointing at `chat/ai`. Migrating is a one-line import change:
+
+```diff
+- import { toAiMessages } from "chat";
++ import { toAiMessages } from "chat/ai";
+```

package/docs/ai/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "AI",
+  "pages": ["index", "ai-sdk-tools", "to-ai-messages", "types"]
+}

package/docs/{api → ai}/to-ai-messages.mdx

@@ -2,18 +2,31 @@
 title: toAiMessages
 description: Convert Chat SDK messages to AI SDK conversation format.
 type: reference
+related:
+  - /docs/ai
+  - /docs/ai/ai-sdk-tools
+  - /docs/ai/types
+  - /docs/streaming
 ---
 
-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[]`.
+Convert an array of [`Message`](/docs/api/message) objects into the `{ role, content }[]` format expected by the AI SDK. The output is structurally compatible with AI SDK's `ModelMessage[]`.
 
 ```typescript
-import { toAiMessages } from "chat";
+import { toAiMessages } from "chat/ai";
 ```
 
+<Callout>
+  `toAiMessages` is also re-exported from the main `chat` entrypoint
+  for backwards compatibility (with a `@deprecated` JSDoc hint), but
+  new code should import it from [`chat/ai`](/docs/ai) alongside
+  [`createChatTools`](/docs/ai/ai-sdk-tools) and the rest of the AI
+  utilities.
+</Callout>
+
 ## Usage
 
 ```typescript title="lib/bot.ts" lineNumbers
-import { toAiMessages } from "chat";
+import { toAiMessages } from "chat/ai";
 
 bot.onSubscribedMessage(async (thread, message) => {
   const result = await thread.adapter.fetchMessages(thread.id, { limit: 20 });