chat 4.26.0 → 4.27.0

package/dist/jsx-runtime.js

@@ -7,7 +7,7 @@ import {
   jsxs,
   toCardElement,
   toModalElement
-} from "./chunk-OPV5U4WG.js";
+} from "./chunk-AN7MRAVW.js";
 export {
   Fragment,
   isCardLinkProps,

package/docs/adapters.mdx

@@ -16,52 +16,52 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 
 | 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) |
 |---------|-------|-------|-------------|---------|---------|--------|--------|-----------|
-| Post message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Edit message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Delete message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| File uploads | ✅ | ✅ | ❌ | ✅ | ⚠️ Single file | ❌ | ❌ | ✅ Images, audio, docs |
-| Streaming | ✅ Native | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ❌ | ❌ | ❌ |
-| Scheduled messages | ✅ Native | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file | <Cross /> | <Cross /> | <Check /> Images, audio, docs |
+| Streaming | <Check /> Native | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Cross /> | <Cross /> | <Cross /> |
+| Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Rich content
 
 | Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
 |---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
 | Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates |
-| Buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard callbacks | ❌ | ❌ | ✅ Interactive replies |
-| Link buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard URLs | ❌ | ❌ | ❌ |
-| Select menus | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Tables | ✅ Block Kit | ✅ GFM | ⚠️ ASCII | ✅ GFM | ⚠️ ASCII | ✅ GFM | ✅ GFM | ❌ |
-| Fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ Template variables |
-| Images in cards | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
-| Modals | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard callbacks | <Cross /> | <Cross /> | <Check /> Interactive replies |
+| Link buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard URLs | <Cross /> | <Cross /> | <Cross /> |
+| Select menus | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Tables | <Check /> Block Kit | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Check /> GFM | <Cross /> |
+| Fields | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Template variables |
+| Images in cards | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Check /> |
+| Modals | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Conversations
 
 | Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
 |---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Slash commands | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Mentions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Add reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Remove reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | ❌ |
-| Typing indicator | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
-| DMs | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
-| Ephemeral messages | ✅ Native | ❌ | ✅ Native | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Slash commands | <Check /> | <Cross /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Mentions | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Add reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Remove reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Warn /> | <Warn /> | <Cross /> |
+| Typing indicator | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
+| DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
+| Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Message history
 
 | Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
 |---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Fetch messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ✅ | ⚠️ Cached sent messages only |
-| Fetch single message | ✅ | ❌ | ❌ | ❌ | ⚠️ Cached | ❌ | ❌ | ⚠️ Cached sent messages only |
-| Fetch thread info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Fetch channel messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ❌ | ⚠️ Cached sent messages only |
-| List threads | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
-| Fetch channel info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
-| Post channel message | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
+| Fetch messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Check /> | <Warn /> Cached sent messages only |
+| Fetch single message | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached | <Cross /> | <Cross /> | <Warn /> Cached sent messages only |
+| Fetch thread info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Fetch channel messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Cross /> | <Warn /> Cached sent messages only |
+| List threads | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> |
+| Fetch channel info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Post channel message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
 
 <Callout type="info">
-⚠️ indicates partial support — the feature works with limitations. See individual adapter pages for details.
+<Warn /> indicates partial support — the feature works with limitations. See individual adapter pages for details.
 </Callout>
 
 ## How adapters work

package/docs/api/chat.mdx

@@ -255,7 +255,8 @@ bot.onModalSubmit("feedback", async (event) => {
 
 Returns `ModalResponse | undefined` to control the modal after submission:
 
-- `{ action: "close" }` — close the modal
+- `{ action: "close" }` — close the current view (goes back one level in the stack)
+- `{ action: "clear" }` — close all views and dismiss the modal entirely
 - `{ action: "errors", errors: { fieldId: "message" } }` — show validation errors
 - `{ action: "update", modal: ModalElement }` — replace the modal content
 - `{ action: "push", modal: ModalElement }` — push a new modal view onto the stack
@@ -443,6 +444,89 @@ await dm.post("Hello via DM!");
 const dm = await bot.openDM(message.author);
 ```
 
+### getUser
+
+Look up user information by user ID. Returns a `UserInfo` object with name, email, avatar, and bot status, or `null` if the user was not found. Supported on Slack, Microsoft Teams, Discord, Google Chat, GitHub, Linear, and Telegram. Other adapters will throw `NOT_SUPPORTED`.
+
+```typescript
+const user = await bot.getUser("U123456");
+console.log(user?.email);    // "alice@company.com"
+console.log(user?.fullName); // "Alice Smith"
+```
+
+```typescript
+// Or with an Author object from a message handler
+const user = await bot.getUser(message.author);
+```
+
+<TypeTable
+  type={{
+    userId: {
+      description: 'Platform-specific user ID.',
+      type: 'string',
+    },
+    userName: {
+      description: 'Username/handle.',
+      type: 'string',
+    },
+    fullName: {
+      description: 'Display name / full name.',
+      type: 'string',
+    },
+    isBot: {
+      description: 'Whether the user is a bot.',
+      type: 'boolean',
+    },
+    email: {
+      description: 'Email address (requires scopes on some platforms).',
+      type: 'string | undefined',
+    },
+    avatarUrl: {
+      description: 'Profile image URL.',
+      type: 'string | undefined',
+    },
+  }}
+/>
+
+<Callout type="info">
+  **Per-platform constraints:**
+  - **Slack** — requires both `users:read` and `users:read.email` scopes (the email scope must be granted at OAuth install time).
+  - **Discord** — bot tokens never see email (the `email` OAuth scope only applies in user-context auth).
+  - **Telegram** — bots can only look up users who have previously messaged them.
+  - **Microsoft Teams** — only works for users who previously interacted with the bot (cached from webhook activity). `avatarUrl` is not returned (Graph API requires a separate photo call).
+  - **Google Chat** — same caching constraint as Teams: only users seen in prior webhooks.
+  - **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.
+</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:
+
+```typescript
+import { ChatError } from "chat";
+
+try {
+  const user = await bot.getUser(userId);
+  if (!user) {
+    // User not found on this platform
+  }
+} catch (error) {
+  if (error instanceof ChatError && error.code === "NOT_SUPPORTED") {
+    // This adapter doesn't support user lookups
+  }
+}
+```
+
+### thread
+
+Get a Thread handle by its thread ID. Useful for posting to threads outside of webhook contexts (e.g. cron jobs, external triggers).
+
+```typescript
+const thread = bot.thread("slack:C123ABC:1234567890.123456");
+await thread.post("Hello from a cron job!");
+```
+
 ### channel
 
 Get a Channel by its channel ID.

package/docs/api/message.mdx

@@ -149,6 +149,10 @@ All adapters return `false` if the bot ID isn't known yet. This is a safe defaul
       description: 'Fetch the attachment data. Handles platform auth automatically.',
       type: '() => Promise<Buffer> | undefined',
     },
+    fetchMetadata: {
+      description: 'Platform-specific IDs for reconstructing fetchData after serialization (e.g. WhatsApp mediaId, Telegram fileId).',
+      type: 'Record<string, string> | undefined',
+    },
   }}
 />
 
@@ -208,4 +212,4 @@ const json = message.toJSON();
 const restored = Message.fromJSON(json);
 ```
 
-The serialized format converts `Date` fields to ISO strings and omits non-serializable fields like `data` buffers and `fetchData` functions.
+The serialized format converts `Date` fields to ISO strings and omits non-serializable fields like `data` buffers and `fetchData` functions. The `fetchMetadata` field is preserved so that adapters can reconstruct `fetchData` when the message is rehydrated from a queue.

package/docs/api/thread.mdx

@@ -4,7 +4,7 @@ description: Represents a conversation thread with methods for posting, subscrib
 type: reference
 ---
 
-A `Thread` is provided to your event handlers and represents a conversation thread on any platform. You don't create threads directly — they come from handler callbacks or `chat.openDM()`.
+A `Thread` is provided to your event handlers and represents a conversation thread on any platform. You can also create thread handles directly using `chat.thread()` or `chat.openDM()`.
 
 ## Properties
 
@@ -114,6 +114,28 @@ await scheduled.cancel();
 Streaming and file uploads are not supported in scheduled messages.
 </Callout>
 
+## getParticipants
+
+Get the unique human participants in a thread. Returns deduplicated authors, excluding all bots. Useful for subscribing only to 1:1 conversations and unsubscribing when others join.
+
+```typescript
+const participants = await thread.getParticipants();
+
+// Subscribe only when one person is talking to the bot
+if (participants.length === 1) {
+  await thread.subscribe();
+}
+
+// Unsubscribe when the thread becomes a group conversation
+if (participants.length > 1) {
+  await thread.unsubscribe();
+}
+```
+
+<Callout type="warn">
+  Each call fetches the full message history to find all participants. On threads with long history this makes multiple API calls to the platform. Consider checking `message.author` against a known set before calling `getParticipants()` on every incoming message.
+</Callout>
+
 ## subscribe / unsubscribe
 
 Manage thread subscriptions. Subscribed threads route all messages to `onSubscribedMessage` handlers.

package/docs/contributing/publishing.mdx

@@ -159,3 +159,36 @@ You should see your exported symbols (`createMatrixAdapter`, `MatrixAdapter`, et
 - Watch the [Chat SDK changelog](https://github.com/vercel/chat/releases) for new features and breaking changes
 - Run your test suite against new Chat SDK releases before they ship to catch compatibility issues early
 - When the `Adapter` interface adds new optional methods, consider implementing them to keep your adapter feature-complete
+
+## Listing on chat-sdk.dev
+
+Community adapters can be listed on the [Adapters](https://chat-sdk.dev/adapters) page by opening a PR that adds an entry to `apps/docs/adapters.json` in the [Chat SDK repo](https://github.com/vercel/chat). Your adapter's README is fetched from GitHub at build time and rendered on its dedicated page.
+
+### Pin your README to a commit or tag
+
+<Callout type="warn">
+  The `readme` field **must** reference a specific commit SHA or tag — not a branch name like `main`.
+</Callout>
+
+The docs site re-renders on every deploy, so an unpinned `readme` would serve whatever currently sits at your default branch — including edits made after the listing PR was reviewed. Pinning freezes the rendered content at the state we approved; new content goes live through a follow-up PR that bumps the ref.
+
+```json title="apps/docs/adapters.json"
+{
+  "name": "My Adapter",
+  "slug": "my-adapter",
+  "type": "platform",
+  "community": true,
+  "packageName": "chat-adapter-my-thing",
+  "readme": "https://github.com/your-org/chat-adapter-my-thing/tree/v1.2.0"
+}
+```
+
+Accepted `readme` formats:
+
+| Format | Example |
+|--------|---------|
+| Repo root at a tag | `https://github.com/owner/repo/tree/v1.0.0` |
+| Repo root at a commit | `https://github.com/owner/repo/tree/abc1234...` |
+| Subpath in a monorepo | `https://github.com/owner/repo/tree/<ref>/packages/adapter` |
+
+Unpinned refs (e.g., `tree/main`, or omitting `/tree/<ref>` entirely) will emit a build warning and are rejected during PR review.

package/docs/files.mdx

@@ -75,3 +75,4 @@ bot.onSubscribedMessage(async (thread, message) => {
 | `width` | `number` (optional) | Image width |
 | `height` | `number` (optional) | Image height |
 | `fetchData` | `() => Promise<Buffer>` (optional) | Download the file data |
+| `fetchMetadata` | `Record<string, string>` (optional) | Platform-specific IDs for reconstructing `fetchData` after serialization |

package/docs/getting-started.mdx

@@ -25,14 +25,4 @@ Connect your bot to chat platforms and persist state across restarts.
 
 Browse all official and community adapters on the [Adapters](/adapters) page.
 
-## Guides
-
-Step-by-step tutorials to get up and running on your platform of choice.
-
-<Cards>
-  <Card title="Slack bot with Next.js and Redis" description="Build a Slack bot from scratch using Chat SDK, Next.js, and Redis." href="/docs/guides/slack-nextjs" />
-  <Card title="Durable chat sessions with Next.js, Workflow, and Redis" description="Build a bot whose thread sessions survive restarts by combining Chat SDK with Workflow." href="/docs/guides/durable-chat-sessions-nextjs" />
-  <Card title="Schedule Slack posts with Next.js, Workflow, and Neon" description="Build durable scheduled posts backed by Neon and Workflow timers." href="/docs/guides/scheduled-posts-neon" />
-  <Card title="Code review GitHub bot with Hono and Redis" description="Build a GitHub bot that reviews pull requests using AI SDK, Vercel Sandbox, and Chat SDK." href="/docs/guides/code-review-hono" />
-  <Card title="Discord support bot with Nuxt and Redis" description="Build a Discord support bot using Chat SDK, Nuxt, and AI SDK." href="/docs/guides/discord-nuxt" />
-</Cards>
+Step-by-step guides and starter templates are available on the [Resources](/resources) page.

package/docs/meta.json

@@ -15,8 +15,6 @@
     "concurrency",
     "...",
     "error-handling",
-    "---Guides---",
-    "...guides",
     "---API Reference---",
     "...api",
     "---Contributing---",

package/docs/modals.mdx

@@ -87,6 +87,77 @@ A dropdown for selecting a single option.
 | `initialOption` | `string` (optional) | Pre-selected value |
 | `optional` | `boolean` (optional) | Allow empty submission |
 
+### ExternalSelect
+
+A dropdown that loads its options dynamically from a handler as the user types. Useful for large or remote-backed option sets (people, tickets, records) where a static `<Select>` would be impractical. Slack-only.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Field identifier (key in `event.values`) |
+| `label` | `string` | Field label |
+| `placeholder` | `string` (optional) | Placeholder text |
+| `minQueryLength` | `number` (optional) | Minimum characters before the loader fires (Slack default: 3) |
+| `initialOption` | `{ label, value }` (optional) | Pre-selected option when the modal opens (must match an option returned by the loader). For static `<Select>`, `initialOption` is just the value string — for `<ExternalSelect>` it's the full `{ label, value }` object since the loader hasn't run yet. |
+| `optional` | `boolean` (optional) | Allow empty submission |
+
+Register the loader with `onOptionsLoad`:
+
+```tsx title="lib/bot.tsx" lineNumbers
+import { ExternalSelect, Modal } from "chat";
+
+bot.onAction("assign", async (event) => {
+  await event.openModal(
+    <Modal callbackId="assign_form" title="Assign to…">
+      <ExternalSelect
+        id="assignee"
+        label="Assignee"
+        placeholder="Search people"
+        minQueryLength={1}
+      />
+    </Modal>
+  );
+});
+
+bot.onOptionsLoad("assignee", async (event) => {
+  const people = await peopleService.search(event.query);
+  return people.map((p) => ({ label: p.fullName, value: p.id }));
+});
+
+bot.onModalSubmit("assign_form", async (event) => {
+  const assigneeId = event.values.assignee;
+  // …
+});
+```
+
+The selected value arrives in `event.values` on submit just like a static `<Select>`.
+
+#### Grouped options
+
+Return an array of groups instead of a flat options array to render headers between sections (e.g. "Recent" / "All"):
+
+```tsx
+bot.onOptionsLoad("assignee", async (event) => {
+  const [recent, all] = await Promise.all([
+    peopleService.recent(event.user.userId),
+    peopleService.search(event.query),
+  ]);
+  return [
+    { label: "Recent", options: recent.map((p) => ({ label: p.fullName, value: p.id })) },
+    { label: "All", options: all.map((p) => ({ label: p.fullName, value: p.id })) },
+  ];
+});
+```
+
+Slack limits: max 100 groups, max 100 options per group, group label max 75 characters.
+
+<Callout type="warn">
+Slack requires a response within 3 seconds for options requests. The adapter caps the loader at ~2.5s and returns an empty result on timeout — keep your loader fast (cache, prefetch, or narrow the query server-side).
+</Callout>
+
+<Callout type="info">
+**Slack setup:** `ExternalSelect` uses Slack's `block_suggestion` payload, which is dispatched to the **Options Load URL**. In your [Slack app settings](https://api.slack.com/apps) go to **Interactivity & Shortcuts** → **Select Menus** and set the **Options Load URL** to the same endpoint as your Interactivity Request URL (e.g. `https://your-domain.com/api/webhooks/slack`). Without this, typing into an external select will silently return no results.
+</Callout>
+
 ### RadioSelect
 
 A radio button group for mutually exclusive options.
@@ -142,7 +213,8 @@ bot.onModalSubmit("feedback_form", async (event) => {
 
 | Response | Description |
 |----------|-------------|
-| `undefined` or `{ action: "close" }` | Close the modal |
+| `undefined` or `{ action: "close" }` | Close the current view (goes back one level in the stack) |
+| `{ action: "clear" }` | Close all views and dismiss the modal entirely |
 | `{ action: "errors", errors: { fieldId: "message" } }` | Show validation errors on specific fields |
 | `{ action: "update", modal: ModalElement }` | Replace the modal content |
 | `{ action: "push", modal: ModalElement }` | Push a new modal view onto the stack |

package/docs/streaming.mdx

@@ -118,6 +118,7 @@ const stream = (async function* () {
     type: "task_update",
     id: "search-1",
     title: "Searching documents",
+    details: "Querying internal docs and ranking the best matches",
     status: "in_progress",
   } satisfies StreamChunk;
 
@@ -127,6 +128,7 @@ const stream = (async function* () {
     type: "task_update",
     id: "search-1",
     title: "Searching documents",
+    details: "Ranked 3 relevant results",
     status: "complete",
     output: "Found 3 results",
   } satisfies StreamChunk;
@@ -142,16 +144,19 @@ await thread.post(stream);
 | Type | Fields | Description |
 |------|--------|-------------|
 | `markdown_text` | `text` | Streamed text content |
-| `task_update` | `id`, `title`, `status`, `output?` | Tool/step progress cards (`pending`, `in_progress`, `complete`, `error`) |
+| `task_update` | `id`, `title`, `status`, `details?`, `output?` | Tool/step progress cards (`pending`, `in_progress`, `complete`, `error`) with optional extra task context |
 | `plan_update` | `title` | Plan title updates |
 
 ### Task display mode
 
-Control how `task_update` chunks render in Slack by passing `taskDisplayMode` in stream options:
+Control how `task_update` chunks render in Slack by passing `taskDisplayMode` via the adapter's streaming API. These options are currently only available through `adapter.stream()` directly:
 
 ```typescript
-await thread.stream(stream, {
-  taskDisplayMode: "plan", // Group all tasks into a single plan block
+const raw = message.raw as { team_id?: string; team?: string };
+await thread.adapter.stream(thread.id, stream, {
+  recipientUserId: message.author.userId,
+  recipientTeamId: raw.team_id ?? raw.team,
+  taskDisplayMode: "plan",
 });
 ```
 
@@ -167,7 +172,10 @@ Adapters without structured chunk support extract text from `markdown_text` chun
 When streaming in Slack, you can attach Block Kit elements to the final message using `stopBlocks`. This is useful for adding action buttons after a streamed response completes:
 
 ```typescript title="lib/bot.ts" lineNumbers
-await thread.stream(textStream, {
+const raw = message.raw as { team_id?: string; team?: string };
+await thread.adapter.stream(thread.id, textStream, {
+  recipientUserId: message.author.userId,
+  recipientTeamId: raw.team_id ?? raw.team,
   stopBlocks: [
     {
       type: "actions",

package/docs/threads-messages-channels.mdx

@@ -40,6 +40,33 @@ await thread.unsubscribe();
 const subscribed = await thread.isSubscribed();
 ```
 
+### Participants
+
+Get the unique human participants in a thread. Returns deduplicated authors, excluding all bots. Useful for deciding whether to subscribe based on how many humans are in the conversation.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMention(async (thread) => {
+  const participants = await thread.getParticipants();
+  if (participants.length === 1) {
+    await thread.subscribe();
+    await thread.post("I'm here to help!");
+  }
+});
+
+bot.onSubscribedMessage(async (thread) => {
+  const participants = await thread.getParticipants();
+  if (participants.length > 1) {
+    await thread.unsubscribe();
+    return;
+  }
+  // respond...
+});
+```
+
+<Callout type="warn">
+  Each call fetches the full message history to find all participants. On threads with long history this makes multiple API calls to the platform. Consider checking `message.author` against a known set before calling `getParticipants()` on every incoming message.
+</Callout>
+
 ### Typing indicator
 
 ```typescript title="lib/bot.ts"
@@ -144,6 +171,13 @@ interface Author {
 }
 ```
 
+For richer user info (email, avatar), use [`chat.getUser()`](/docs/api/chat#getuser):
+
+```typescript title="lib/bot.ts"
+const user = await bot.getUser(message.author);
+console.log(user?.email); // "alice@company.com"
+```
+
 ### Sent messages
 
 When you post a message, you get back a `SentMessage` with methods to edit, delete, and react:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.26.0",
+  "version": "4.27.0",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,8 @@
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "resources"
   ],
   "dependencies": {
     "@workflow/serde": "4.1.0-beta.2",