chat 4.27.0 → 4.29.0

package/docs/ai/types.mdx

@@ -0,0 +1,243 @@
+---
+title: Types
+description: TypeScript types exported from the chat/ai subpath.
+type: reference
+related:
+  - /docs/ai
+  - /docs/ai/ai-sdk-tools
+  - /docs/ai/to-ai-messages
+---
+
+Every type exported from `chat/ai`. Pulling these from the subpath keeps the optional `ai` and `zod` peer deps out of bundles that don't import them.
+
+```ts
+import type {
+  AiMessage,
+  AiUserMessage,
+  AiAssistantMessage,
+  AiMessagePart,
+  AiTextPart,
+  AiImagePart,
+  AiFilePart,
+  ToAiMessagesOptions,
+  ChatBinding,
+  ChatTools,
+  ChatToolName,
+  ChatToolPreset,
+  ChatWriteToolName,
+  ApprovalConfig,
+  ToolOptions,
+  ToolOverrides,
+} from "chat/ai";
+```
+
+## Conversation messages
+
+Used by [`toAiMessages`](/docs/ai/to-ai-messages) and any agent prompt you build by hand. The shapes are structurally compatible with AI SDK's `ModelMessage` so the result is directly assignable to `prompt` / `messages`.
+
+### AiMessage
+
+```typescript
+type AiMessage = AiUserMessage | AiAssistantMessage;
+```
+
+A single normalized turn in a conversation — the array form is what AI SDK calls expect.
+
+### AiUserMessage
+
+```typescript
+interface AiUserMessage {
+  role: "user";
+  content: string | AiMessagePart[];
+}
+```
+
+User content can be plain text, or a multipart array when attachments are present.
+
+### AiAssistantMessage
+
+```typescript
+interface AiAssistantMessage {
+  role: "assistant";
+  content: string;
+}
+```
+
+Assistant turns are always plain strings — `toAiMessages` produces this for any message authored by the bot itself (`author.isMe === true`).
+
+### AiMessagePart
+
+```typescript
+type AiMessagePart = AiTextPart | AiImagePart | AiFilePart;
+```
+
+The discriminated union used inside multipart user messages.
+
+### AiTextPart
+
+```typescript
+interface AiTextPart {
+  type: "text";
+  text: string;
+}
+```
+
+### AiImagePart
+
+```typescript
+interface AiImagePart {
+  type: "image";
+  image: DataContent | URL;
+  mediaType?: string;
+}
+```
+
+`DataContent` matches AI SDK's type — `string | Uint8Array | ArrayBuffer | Buffer`.
+
+### AiFilePart
+
+```typescript
+interface AiFilePart {
+  type: "file";
+  data: DataContent | URL;
+  filename?: string;
+  mediaType: string;
+}
+```
+
+`toAiMessages` emits text-like attachments (JSON, XML, YAML, source files, etc.) as file parts.
+
+### ToAiMessagesOptions
+
+```typescript
+interface ToAiMessagesOptions {
+  includeNames?: boolean;
+  transformMessage?: (
+    aiMessage: AiMessage,
+    source: Message
+  ) => AiMessage | null | Promise<AiMessage | null>;
+  onUnsupportedAttachment?: (
+    attachment: Attachment,
+    message: Message
+  ) => void;
+}
+```
+
+See [`toAiMessages`](/docs/ai/to-ai-messages) for behavior and examples.
+
+## Tools
+
+Returned by [`createChatTools`](/docs/ai/ai-sdk-tools) and used to configure it.
+
+### ChatBinding
+
+```typescript
+type ChatBinding = Chat<any, any>;
+```
+
+Whatever [`Chat`](/docs/api/chat) instance the tools should dispatch operations against. The generics are intentionally loose so any strongly-typed `Chat<TAdapters, TState>` is assignable.
+
+### ChatTools
+
+```typescript
+type ChatTools = ReturnType<typeof createChatTools>;
+```
+
+Convenience alias for the object returned by `createChatTools` — handy when you want to type a wrapper or pass the toolset around.
+
+### ChatToolPreset
+
+```typescript
+type ChatToolPreset = "reader" | "messenger" | "moderator";
+```
+
+Predefined toolset scopes. See [Presets](/docs/ai/ai-sdk-tools#presets) for the exact tool list per preset.
+
+### ChatToolName
+
+```typescript
+type ChatToolName =
+  | "fetchMessages"
+  | "fetchChannelMessages"
+  | "fetchThread"
+  | "listThreads"
+  | "getThreadParticipants"
+  | "getChannelInfo"
+  | "getUser"
+  | "startTyping"
+  | "postMessage"
+  | "postChannelMessage"
+  | "sendDirectMessage"
+  | "editMessage"
+  | "deleteMessage"
+  | "addReaction"
+  | "removeReaction"
+  | "subscribeThread"
+  | "unsubscribeThread";
+```
+
+The names of every generated tool. Useful when typing per-tool overrides.
+
+### ChatWriteToolName
+
+```typescript
+type ChatWriteToolName =
+  | "postMessage"
+  | "postChannelMessage"
+  | "sendDirectMessage"
+  | "editMessage"
+  | "deleteMessage"
+  | "addReaction"
+  | "removeReaction"
+  | "subscribeThread"
+  | "unsubscribeThread";
+```
+
+The names of every mutating tool. Useful when wiring per-tool approval overrides.
+
+### ApprovalConfig
+
+```typescript
+type ApprovalConfig =
+  | boolean
+  | Partial<Record<ChatWriteToolName, boolean>>;
+```
+
+Controls the `requireApproval` option:
+
+- `true` (default) — every write tool needs approval.
+- `false` — no write tool needs approval.
+- object — per-tool override; unspecified write tools fall back to `true`.
+
+### ToolOptions
+
+```typescript
+interface ToolOptions {
+  needsApproval?: boolean;
+}
+```
+
+Common options accepted by every standalone write-tool factory (e.g. `postMessage(chat, { needsApproval: false })`).
+
+### ToolOverrides
+
+```typescript
+type ToolOverrides = Partial<
+  Pick<
+    Tool,
+    | "description"
+    | "inputExamples"
+    | "metadata"
+    | "needsApproval"
+    | "onInputAvailable"
+    | "onInputDelta"
+    | "onInputStart"
+    | "providerOptions"
+    | "strict"
+    | "title"
+    | "toModelOutput"
+  >
+>;
+```
+
+Per-tool overrides accepted by `createChatTools({ overrides })`. Core fields like `execute`, `inputSchema`, `outputSchema`, `type`, `id`, and `args` are intentionally excluded so tool semantics stay stable across upgrades.

package/docs/api/cards.mdx

@@ -100,6 +100,10 @@ Button({ id: "delete", label: "Delete", style: "danger", value: "item-123" })
       type: '"action" | "modal"',
       default: '"action"',
     },
+    callbackUrl: {
+      description: 'URL to POST action data to when this button is clicked.',
+      type: 'string',
+    },
   }}
 />
 

package/docs/api/chat.mdx

@@ -74,9 +74,36 @@ bot.onNewMention(async (thread, message) => {
   }}
 />
 
+### onDirectMessage
+
+Fires for every direct message when registered. Direct message handlers run before `onSubscribedMessage`, `onNewMention`, and pattern handlers. If no direct message handler is registered, unsubscribed DMs fall through to `onNewMention` for backward compatibility.
+
+```typescript
+bot.onDirectMessage(async (thread, message, channel) => {
+  await thread.post(`Got your DM in ${channel.id}: ${message.text}`);
+});
+```
+
+<TypeTable
+  type={{
+    thread: {
+      description: 'The DM thread where the message occurred.',
+      type: 'Thread',
+    },
+    message: {
+      description: 'The direct message.',
+      type: 'Message',
+    },
+    channel: {
+      description: 'The DM channel.',
+      type: 'Channel',
+    },
+  }}
+/>
+
 ### onSubscribedMessage
 
-Fires for every new message in a subscribed thread. Once subscribed, all messages (including @-mentions) route here instead of `onNewMention`.
+Fires for every new message in a subscribed non-DM thread. Once subscribed, messages (including @-mentions) route here instead of `onNewMention`. DM threads route to `onDirectMessage` first when a direct message handler is registered.
 
 ```typescript
 bot.onSubscribedMessage(async (thread, message) => {
@@ -168,7 +195,9 @@ Fires when a user clicks a button or selects an option in a card.
 ```typescript
 // Single action
 bot.onAction("approve", async (event) => {
-  await event.thread.post("Approved!");
+  if (event.thread) {
+    await event.thread.post("Approved!");
+  }
 });
 
 // Multiple actions
@@ -193,8 +222,8 @@ bot.onAction(async (event) => { /* ... */ });
       type: 'Author',
     },
     'event.thread': {
-      description: 'The thread containing the card.',
-      type: 'Thread',
+      description: 'The thread containing the card, or null for view-based actions.',
+      type: 'Thread | null',
     },
     'event.triggerId': {
       description: 'Trigger ID for opening modals (platform-specific, may expire quickly).',
@@ -261,9 +290,47 @@ Returns `ModalResponse | undefined` to control the modal after submission:
 - `{ action: "update", modal: ModalElement }` — replace the modal content
 - `{ action: "push", modal: ModalElement }` — push a new modal view onto the stack
 
+### onOptionsLoad
+
+Fires when an `ExternalSelect` requests options dynamically. The handler is keyed on the select's `id` and must return options synchronously enough for Slack's 3-second budget (the adapter caps the loader at ~2.5s and substitutes an empty result on timeout). Slack-only.
+
+```typescript
+bot.onOptionsLoad("assignee", async (event) => {
+  const people = await peopleService.search(event.query);
+  return people.map((p) => ({ label: p.fullName, value: p.id }));
+});
+```
+
+Return an array of `OptionsLoadGroup` (`{ label, options }[]`) instead of a flat array to render grouped headers (e.g. "Recent" / "All"). Slack limits: max 100 groups, max 100 options per group.
+
+<TypeTable
+  type={{
+    'event.actionId': {
+      description: 'The id of the select requesting options (matches the id passed to bot.onOptionsLoad).',
+      type: 'string',
+    },
+    'event.query': {
+      description: 'The text the user has typed so far.',
+      type: 'string',
+    },
+    'event.user': {
+      description: 'The user requesting options.',
+      type: 'Author',
+    },
+    'event.adapter': {
+      description: 'The adapter that received this event.',
+      type: 'Adapter',
+    },
+    'event.raw': {
+      description: 'Raw platform-specific payload.',
+      type: 'unknown',
+    },
+  }}
+/>
+
 ### onSlashCommand
 
-Fires when a user invokes a `/command` in the message composer. Currently supported on Slack.
+Fires when a user invokes a `/command` in the message composer. Currently supported on Slack and Discord.
 
 ```typescript
 // Specific command
@@ -426,12 +493,55 @@ bot.webhooks.teams(request, { waitUntil });
 
 ### getAdapter
 
-Get an adapter instance by name.
+Get a typed adapter instance by name.
 
 ```typescript
 const slack = bot.getAdapter("slack");
 ```
 
+#### Direct client access
+
+Access the platform's typed native API client directly via an SDK-named getter — `.webClient` on Slack, `.linearClient` on Linear, `.octokit` on GitHub:
+
+```typescript
+// Slack - full WebClient from @slack/web-api
+const slack = bot.getAdapter("slack").webClient;
+await slack.pins.add({ channel: "C123ABC", timestamp: "1234567890.123456" });
+
+// Linear - full LinearClient from @linear/sdk
+const linear = bot.getAdapter("linear").linearClient;
+const issue = await linear.issue("ENG-123");
+const project = await issue.project;
+
+// GitHub - full Octokit from @octokit/rest
+const github = bot.getAdapter("github").octokit;
+const { data: pulls } = await github.rest.pulls.list({
+  owner: "vercel",
+  repo: "chat",
+  state: "open",
+});
+```
+
+The client uses the credentials from your adapter config. For multi-tenant / multi-workspace adapters (Slack, Linear, GitHub), it returns the client bound to the credentials for the current webhook request context.
+
+<Callout type="info">
+  The previous `.client` getter still works on all three adapters as a deprecated alias for `.webClient` / `.linearClient` / `.octokit`.
+</Callout>
+
+<Callout type="warn">
+  Multi-tenant adapters (GitHub App without a fixed installation ID, Linear with per-org OAuth, Slack in multi-workspace mode) require a webhook handler context to resolve credentials when the native client getter is accessed. Calling it outside a handler throws.
+
+  For Slack, you can also bind a token explicitly outside a webhook with `adapter.withBotToken(token, () => adapter.webClient.…)` — useful for cron jobs or workflows. The same pattern is required when `botToken` is configured as an async resolver function, since `.webClient` resolves the token synchronously.
+
+  Single-tenant adapters (PAT, API key, static `botToken` string, or a synchronous `botToken` resolver) work anywhere.
+</Callout>
+
+| Adapter | Getter | Type |
+|---------|--------|------|
+| Slack | `.webClient` | `WebClient` from `@slack/web-api` |
+| Linear | `.linearClient` | `LinearClient` from `@linear/sdk` |
+| GitHub | `.octokit` | `Octokit` from `@octokit/rest` |
+
 ### openDM
 
 Open a direct message thread with a user.
@@ -498,10 +608,16 @@ const user = await bot.getUser(message.author);
   - **GitHub** — `email` is `null` unless the user made it public, or you authenticated with the `user:email` scope.
   - **Linear** — full profile (incl. email + avatar) for any active workspace member.
 
-  Fields that aren't available return `undefined`. Numeric user IDs (Discord/Telegram/GitHub) can be ambiguous when multiple of those adapters are registered — call the platform's adapter directly (`adapter.getUser(userId)`) in that case.
+  Fields that aren't available return `undefined`. Numeric user IDs (Discord/Telegram/GitHub) can be ambiguous when multiple of those adapters are registered — `bot.getUser` throws a `ChatError` with code `AMBIGUOUS_USER_ID` in that case. Pass an `Author` from a message handler (which already carries the adapter), or call the adapter directly (`adapter.getUser(userId)`).
 </Callout>
 
-Adapters that don't support user lookups will throw a `ChatError` with code `NOT_SUPPORTED`. Handle both cases if your bot runs on multiple platforms:
+`bot.getUser` throws a `ChatError` in three cases. Handle them if your bot runs on multiple platforms:
+
+| Code | When |
+|------|------|
+| `NOT_SUPPORTED` | The resolved adapter doesn't implement `getUser` (e.g. WhatsApp) |
+| `AMBIGUOUS_USER_ID` | A numeric user ID could belong to more than one registered adapter (Discord/Telegram/GitHub) |
+| `UNKNOWN_USER_ID_FORMAT` | The `userId` string doesn't match any registered platform's ID format |
 
 ```typescript
 import { ChatError } from "chat";
@@ -512,8 +628,14 @@ try {
     // User not found on this platform
   }
 } catch (error) {
-  if (error instanceof ChatError && error.code === "NOT_SUPPORTED") {
-    // This adapter doesn't support user lookups
+  if (error instanceof ChatError) {
+    if (error.code === "NOT_SUPPORTED") {
+      // This adapter doesn't support user lookups
+    } else if (error.code === "AMBIGUOUS_USER_ID") {
+      // Pass message.author or call adapter.getUser(userId) directly
+    } else if (error.code === "UNKNOWN_USER_ID_FORMAT") {
+      // userId doesn't match any known platform format
+    }
   }
 }
 ```

package/docs/api/index.mdx

@@ -20,17 +20,17 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | [`Message`](/docs/api/message) | Normalized message with text, AST, author, and metadata |
 | [`ScheduledMessage`](/docs/api/thread#scheduledmessage) | Returned by `thread.schedule()` / `channel.schedule()` with `cancel()` |
 
-## Utilities
-
-| Export | Description |
-|--------|-------------|
-| [`toAiMessages`](/docs/api/to-ai-messages) | Convert `Message[]` to AI SDK `{ role, content }[]` format |
-
 ## Message formats
 
 | Export | Description |
 |--------|-------------|
 | [`PostableMessage`](/docs/api/postable-message) | Union type accepted by `thread.post()` |
+| [`Plan`](/docs/api/postable-message#plan) | Step-by-step task list that mutates after posting |
+| [`StreamingPlan`](/docs/api/postable-message#streamingplan) | Wraps an async iterable with platform-specific streaming options |
 | [`Cards`](/docs/api/cards) | Rich card components — `Card`, `Text`, `Button`, `Actions`, etc. |
 | [`Markdown`](/docs/api/markdown) | AST builder functions — `root`, `paragraph`, `text`, `strong`, etc. |
 | [`Modals`](/docs/api/modals) | Modal form components — `Modal`, `TextInput`, `Select`, etc. |
+
+## AI utilities
+
+`toAiMessages`, `createChatTools`, and the supporting types live in the [`chat/ai`](/docs/ai) subpath — see the [AI section](/docs/ai) for the full reference.

package/docs/api/markdown.mdx

@@ -15,6 +15,25 @@ import {
 } from "chat";
 ```
 
+## Type re-exports
+
+The chat package re-exports mdast's union and content types so adapters and downstream code can build exhaustively-typed AST walkers without depending on `mdast` directly:
+
+```typescript
+import type { Nodes, Root, Content } from "chat";
+
+function render(node: Nodes): string {
+  switch (node.type) {
+    case "text": return node.value;
+    case "strong": return node.children.map(render).join("");
+    // ...
+    default: throw new Error(`Unhandled: ${node satisfies never}`);
+  }
+}
+```
+
+Adapters use this pattern to make the type checker reject the build when a new mdast node type is introduced upstream.
+
 ## Node builders
 
 ### root
@@ -222,7 +241,7 @@ const value = getNodeValue(node);       // string | undefined
 
 ### tableToAscii
 
-Render an mdast `Table` node as a padded ASCII table string. Used by adapters that lack native table support (Slack, Google Chat, Discord, Telegram).
+Render an mdast `Table` node as a padded ASCII table string. Used by adapters that lack native table support (Google Chat, Discord, Telegram).
 
 ```typescript
 import { parseMarkdown, tableToAscii, isTableNode } from "chat";
@@ -261,17 +280,21 @@ The SDK uses mdast as the canonical format and each adapter converts it to the p
 
 | Feature | Slack | Teams | Google Chat |
 |---------|-------|-------|-------------|
-| Bold | `*text*` | `**text**` | `*text*` |
+| Bold | `**text**` | `**text**` | `*text*` |
 | Italic | `_text_` | `_text_` | `_text_` |
-| Strikethrough | `~text~` | `~~text~~` | `~text~` |
+| Strikethrough | `~~text~~` | `~~text~~` | `~text~` |
 | Code | `` `code` `` | `` `code` `` | `` `code` `` |
 | Code blocks | ```` ``` ```` | ```` ``` ```` | ```` ``` ```` |
-| Links | `<url\|text>` | `[text](url)` | `[text](url)` |
+| Links | `[text](url)` | `[text](url)` | `[text](url)` |
 | Lists | Supported | Supported | Supported |
 | Blockquotes | `>` | `>` | Simulated with `>` prefix |
-| Tables | ASCII fallback | Native GFM | ASCII fallback |
+| Tables | Native (markdown_text) | Native GFM | ASCII fallback |
 | Mentions | `<@USER>` | `<at>name</at>` | `<users/{id}>` |
 
+<Callout type="info">
+Slack accepts standard markdown via the `markdown_text` field on `chat.postMessage` and friends, so the SDK passes markdown through directly. Incoming Slack messages still arrive as legacy mrkdwn (`*bold*`, `<url|text>`) and are parsed transparently. If you need to send mrkdwn yourself, use `{ raw: "..." }`.
+</Callout>
+
 <Callout type="info">
 You don't need to worry about these differences when using the SDK — the AST builders and `parseMarkdown` handle conversion automatically. This table is useful if you're working with `raw` platform payloads or debugging formatting issues.
 </Callout>

package/docs/api/message.mdx

@@ -54,6 +54,10 @@ import { Message } from "chat";
       description: 'Whether the bot was @-mentioned in this message.',
       type: 'boolean | undefined',
     },
+    subject: {
+      description: 'Resolves the parent resource (issue, PR) this message is about. Returns null on chat platforms. See [Message Subject](/docs/subject).',
+      type: 'Promise<MessageSubject | null>',
+    },
   }}
 />
 
@@ -190,7 +194,7 @@ Links found in incoming messages are extracted and exposed as `LinkPreview` obje
 />
 
 <Callout type="info">
-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.
+When using [`toAiMessages()`](/docs/ai/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
@@ -200,6 +204,55 @@ When using [`toAiMessages()`](/docs/api/to-ai-messages), link metadata is automa
 | Slack | URLs from `rich_text` blocks or `<url>` text patterns | Slack message links (`*.slack.com/archives/...`) |
 | Others | Not yet — `links` is always `[]` | — |
 
+## MessageSubject
+
+Returned by `message.subject` on platforms with parent resources. See [Message Subject](/docs/subject) for usage.
+
+<TypeTable
+  type={{
+    type: {
+      description: 'Resource kind, e.g. "issue" or "pull_request".',
+      type: 'string',
+    },
+    id: {
+      description: 'Resource identifier (e.g. "ENG-123" or "42").',
+      type: 'string',
+    },
+    title: {
+      description: 'Resource title.',
+      type: 'string | undefined',
+    },
+    description: {
+      description: 'Full description/body in markdown.',
+      type: 'string | undefined',
+    },
+    status: {
+      description: 'Current status (e.g. "In Progress", "open").',
+      type: 'string | undefined',
+    },
+    url: {
+      description: 'Web URL to the resource.',
+      type: 'string | undefined',
+    },
+    author: {
+      description: 'Resource creator.',
+      type: '{ id: string; name: string } | undefined',
+    },
+    assignee: {
+      description: 'Current assignee.',
+      type: '{ id: string; name: string } | undefined',
+    },
+    labels: {
+      description: 'Labels/tags.',
+      type: 'string[] | undefined',
+    },
+    raw: {
+      description: 'Full platform API response.',
+      type: 'unknown',
+    },
+  }}
+/>
+
 ## Serialization
 
 Messages can be serialized for workflow engines and external systems.

package/docs/api/meta.json

@@ -7,6 +7,7 @@
     "channel",
     "message",
     "postable-message",
+    "transcripts",
     "cards",
     "markdown",
     "modals"

package/docs/api/modals.mdx

@@ -54,6 +54,10 @@ bot.onAction("open-form", async (event) => {
       type: 'boolean',
       default: 'false',
     },
+    callbackUrl: {
+      description: 'URL to POST form values to when the modal is submitted.',
+      type: 'string',
+    },
     privateMetadata: {
       description: 'Arbitrary string passed through the modal lifecycle (e.g., JSON context).',
       type: 'string',
@@ -167,6 +171,52 @@ Select({
   }}
 />
 
+## ExternalSelect
+
+Dropdown that loads options dynamically from a handler as the user types. Slack-only. Pair with [`bot.onOptionsLoad`](/docs/api/chat#onoptionsload) to supply options. See [Modals → ExternalSelect](/docs/modals#externalselect) for a full example, grouped-options support, and Slack setup notes.
+
+```typescript
+ExternalSelect({
+  id: "assignee",
+  label: "Assignee",
+  placeholder: "Search people",
+  minQueryLength: 1,
+  initialOption: { label: "Alice", value: "U123" },
+})
+```
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Input ID — used as the key in event.values.',
+      type: 'string',
+    },
+    label: {
+      description: 'Label displayed above the select.',
+      type: 'string',
+    },
+    placeholder: {
+      description: 'Placeholder text.',
+      type: 'string',
+    },
+    minQueryLength: {
+      description: 'Minimum characters before the loader fires (Slack default: 3).',
+      type: 'number',
+    },
+    initialOption: {
+      description: 'Pre-selected option when the modal opens. Unlike static Select where initialOption is a value string, ExternalSelect needs the full label/value object since the loader has not run yet.',
+      type: '{ label: string, value: string }',
+    },
+    optional: {
+      description: 'Whether the field can be left empty.',
+      type: 'boolean',
+      default: 'false',
+    },
+  }}
+/>
+
+The loader registered via `bot.onOptionsLoad("assignee", handler)` returns either a flat `SelectOptionElement[]` or `OptionsLoadGroup[]` (`{ label, options }[]`) for grouped options.
+
 ## RadioSelect
 
 Radio button group for mutually exclusive choices.