From e3d7b9b534899aeb7cac0e367c38fa6cc679874a Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Sun, 11 Jan 2026 16:27:26 -0500
Subject: [PATCH 01/12] feat: accept chunks as arguments to
 chat.{start,append,stop}Stream methods

---
 packages/types/src/chunk.ts                   | 89 +++++++++++++++++++
 packages/types/src/index.ts                   |  1 +
 packages/web-api/src/types/request/chat.ts    | 18 +++-
 .../web-api/test/types/methods/chat.test-d.ts | 74 +++++++++++++++
 4 files changed, 181 insertions(+), 1 deletion(-)
 create mode 100644 packages/types/src/chunk.ts

diff --git a/packages/types/src/chunk.ts b/packages/types/src/chunk.ts
new file mode 100644
index 000000000..acc7cdc23
--- /dev/null
+++ b/packages/types/src/chunk.ts
@@ -0,0 +1,89 @@
+/**
+ * Base interface for streaming message chunks.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface Chunk {
+  type: string;
+}
+
+/**
+ * Used for streaming text content with markdown formatting support.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface MarkdownTextChunk extends Chunk {
+  type: 'markdown_text';
+  text: string;
+}
+
+/**
+ * URL source for task update chunks.
+ */
+export interface URLSource {
+  type: 'url';
+  url: string;
+  text: string;
+  icon_url?: string;
+}
+
+/**
+ * Used for displaying tool execution progress in a timeline-style UI.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface TaskUpdateChunk extends Chunk {
+  type: 'task_update';
+  id: string;
+  title: string;
+  status: 'pending' | 'in_progress' | 'complete' | 'error';
+  details?: string;
+  output?: string;
+  sources?: URLSource[];
+}
+
+/**
+ * Union type of all possible chunk types
+ */
+export type AnyChunk = MarkdownTextChunk | TaskUpdateChunk;
+
+/**
+ * Parse a chunk object and return the appropriate typed chunk.
+ * Returns null if the chunk is invalid or unknown.
+ */
+export function parseChunk(chunk: unknown): AnyChunk | null {
+  if (!chunk || typeof chunk !== 'object') {
+    return null;
+  }
+
+  const chunkObj = chunk as Record<string, unknown>;
+
+  if (!('type' in chunkObj) || typeof chunkObj.type !== 'string') {
+    console.warn('Unknown chunk detected and skipped (missing type)', chunk);
+    return null;
+  }
+
+  const { type } = chunkObj;
+
+  if (type === 'markdown_text') {
+    if (typeof chunkObj.text === 'string') {
+      return chunkObj as unknown as MarkdownTextChunk;
+    }
+    console.warn('Invalid MarkdownTextChunk (missing text property)', chunk);
+    return null;
+  }
+
+  if (type === 'task_update') {
+    const taskChunk = chunkObj as Partial<TaskUpdateChunk>;
+    if (
+      typeof taskChunk.id === 'string' &&
+      typeof taskChunk.title === 'string' &&
+      typeof taskChunk.status === 'string' &&
+      ['pending', 'in_progress', 'complete', 'error'].includes(taskChunk.status)
+    ) {
+      return chunkObj as unknown as TaskUpdateChunk;
+    }
+    console.warn('Invalid TaskUpdateChunk (missing required properties)', chunk);
+    return null;
+  }
+
+  console.warn(`Unknown chunk type detected and skipped: ${type}`, chunk);
+  return null;
+}
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 9992536de..2740a2290 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -3,6 +3,7 @@ export * from './block-kit/blocks';
 export * from './block-kit/composition-objects';
 export * from './block-kit/extensions';
 export * from './calls';
+export * from './chunk';
 export * from './dialog';
 export * from './events';
 export * from './message-attachments';
diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts
index 7734d7a7f..bc43a9fb8 100644
--- a/packages/web-api/src/types/request/chat.ts
+++ b/packages/web-api/src/types/request/chat.ts
@@ -1,4 +1,5 @@
 import type {
+  AnyChunk,
   Block, // TODO: these will be combined into one in a new types release
   EntityMetadata,
   KnownBlock,
@@ -168,7 +169,13 @@ export interface Unfurls {
   unfurl_media?: boolean;
 }
 
-export interface ChatAppendStreamArguments extends TokenOverridable, ChannelAndTS, MarkdownText {}
+export interface ChatAppendStreamArguments extends TokenOverridable, ChannelAndTS, MarkdownText {
+  /**
+   * @description An array of {@link https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming chunk objects} to append to the stream.
+   * Either `markdown_text` or `chunks` is required.
+   */
+  chunks?: AnyChunk[];
+}
 
 // https://docs.slack.dev/reference/methods/chat.delete
 export interface ChatDeleteArguments extends ChannelAndTS, AsUser, TokenOverridable {}
@@ -233,6 +240,11 @@ export type ChatScheduledMessagesListArguments = OptionalArgument<
 >;
 
 export interface ChatStartStreamArguments extends TokenOverridable, Channel, Partial<MarkdownText>, ThreadTS {
+  /**
+   * @description An array of {@link https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming chunk objects} to start the stream with.
+   * Either `markdown_text` or `chunks` is required.
+   */
+  chunks?: AnyChunk[];
   /**
    * @description The ID of the team that is associated with `recipient_user_id`.
    * This is required when starting a streaming conversation outside of a DM.
@@ -249,6 +261,10 @@ export type ChatStopStreamArguments = TokenOverridable &
   ChannelAndTS &
   Partial<MarkdownText> &
   Partial<Metadata> & {
+    /**
+     * @description An array of {@link https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming chunk objects} to finalize the stream with.
+     */
+    chunks?: AnyChunk[];
     /**
      * Block formatted elements will be appended to the end of the message.
      */
diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts
index f1ec5f025..09916b0bb 100644
--- a/packages/web-api/test/types/methods/chat.test-d.ts
+++ b/packages/web-api/test/types/methods/chat.test-d.ts
@@ -32,6 +32,26 @@ expectAssignable<Parameters<typeof web.chat.appendStream>>([
     markdown_text: 'hello',
   },
 ]);
+expectAssignable<Parameters<typeof web.chat.appendStream>>([
+  {
+    channel: 'C1234',
+    ts: '1234.56',
+    markdown_text: 'hello',
+    chunks: [
+      {
+        type: 'markdown_text',
+        text: 'Hello world',
+      },
+      {
+        type: 'task_update',
+        id: 'task-1',
+        title: 'Processing request',
+        status: 'in_progress',
+        details: 'Working on it...',
+      },
+    ],
+  },
+]);
 
 // chat.delete
 // -- sad path
@@ -636,6 +656,39 @@ expectAssignable<Parameters<typeof web.chat.startStream>>([
     channel: 'C1234',
     thread_ts: '1234.56',
     markdown_text: 'hello',
+    chunks: [
+      {
+        type: 'markdown_text',
+        text: 'Hello world',
+      },
+      {
+        type: 'task_update',
+        id: 'task-1',
+        title: 'Processing request',
+        status: 'in_progress',
+        details: 'Working on it...',
+      },
+    ],
+  },
+]);
+expectAssignable<Parameters<typeof web.chat.startStream>>([
+  {
+    channel: 'C1234',
+    thread_ts: '1234.56',
+    markdown_text: 'hello',
+    chunks: [
+      {
+        type: 'markdown_text',
+        text: 'Hello world',
+      },
+      {
+        type: 'task_update',
+        id: 'task-1',
+        title: 'Processing request',
+        status: 'in_progress',
+        details: 'Working on it...',
+      },
+    ],
     recipient_team_id: 'T1234',
     recipient_user_id: 'U1234',
   },
@@ -670,6 +723,27 @@ expectAssignable<Parameters<typeof web.chat.stopStream>>([
     blocks: [],
   },
 ]);
+expectAssignable<Parameters<typeof web.chat.stopStream>>([
+  {
+    channel: 'C1234',
+    ts: '1234.56',
+    markdown_text: 'hello',
+    chunks: [
+      {
+        type: 'markdown_text',
+        text: 'Hello world',
+      },
+      {
+        type: 'task_update',
+        id: 'task-1',
+        title: 'Processing request',
+        status: 'in_progress',
+        details: 'Working on it...',
+      },
+    ],
+    blocks: [],
+  },
+]);
 
 // chat.unfurl
 // -- sad path

From 260119954e2df1757d6c1e0d28add29efc27b888 Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Sun, 11 Jan 2026 17:17:17 -0500
Subject: [PATCH 02/12] build: update slack/types version in package json

---
 packages/web-api/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-api/package.json b/packages/web-api/package.json
index 36ffc23bf..c41da4903 100644
--- a/packages/web-api/package.json
+++ b/packages/web-api/package.json
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@slack/logger": "^4.0.0",
-    "@slack/types": "^2.18.0",
+    "@slack/types": "^2.19.0",
     "@types/node": ">=18.0.0",
     "@types/retry": "0.12.0",
     "axios": "^1.11.0",

From 160cfb7aee50dce5759a2968267cbb0da7055562 Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Thu, 15 Jan 2026 17:43:38 -0500
Subject: [PATCH 03/12] fix: make markdown text optional and add missing chunk
 type

---
 packages/types/src/chunk.ts                | 19 ++++++++++++++++++-
 packages/web-api/src/types/request/chat.ts |  2 +-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/packages/types/src/chunk.ts b/packages/types/src/chunk.ts
index acc7cdc23..6acddb06b 100644
--- a/packages/types/src/chunk.ts
+++ b/packages/types/src/chunk.ts
@@ -25,6 +25,15 @@ export interface URLSource {
   icon_url?: string;
 }
 
+/**
+ * An updated title of plans for task and tool calls.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface PlanUpdateChunk extends Chunk {
+  type: 'plan_update';
+  title: string;
+}
+
 /**
  * Used for displaying tool execution progress in a timeline-style UI.
  * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
@@ -42,7 +51,7 @@ export interface TaskUpdateChunk extends Chunk {
 /**
  * Union type of all possible chunk types
  */
-export type AnyChunk = MarkdownTextChunk | TaskUpdateChunk;
+export type AnyChunk = MarkdownTextChunk | PlanUpdateChunk | TaskUpdateChunk;
 
 /**
  * Parse a chunk object and return the appropriate typed chunk.
@@ -70,6 +79,14 @@ export function parseChunk(chunk: unknown): AnyChunk | null {
     return null;
   }
 
+  if(type === 'plan_update') {
+    if (typeof chunkObj.title === 'string') {
+      return chunkObj as unknown as PlanUpdateChunk;
+    }
+    console.warn('Invalid PlanUpdateChunk (missing title property)', chunk);
+    return null;
+  }
+
   if (type === 'task_update') {
     const taskChunk = chunkObj as Partial<TaskUpdateChunk>;
     if (
diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts
index bc43a9fb8..9c5c2292c 100644
--- a/packages/web-api/src/types/request/chat.ts
+++ b/packages/web-api/src/types/request/chat.ts
@@ -169,7 +169,7 @@ export interface Unfurls {
   unfurl_media?: boolean;
 }
 
-export interface ChatAppendStreamArguments extends TokenOverridable, ChannelAndTS, MarkdownText {
+export interface ChatAppendStreamArguments extends TokenOverridable, ChannelAndTS, Partial<MarkdownText> {
   /**
    * @description An array of {@link https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming chunk objects} to append to the stream.
    * Either `markdown_text` or `chunks` is required.

From f510980860d2b9ee9c2a5914dfb4461d9248d208 Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Fri, 16 Jan 2026 14:49:03 -0500
Subject: [PATCH 04/12] feat: chunk processing in chat stream helper

---
 packages/web-api/src/chat-stream.ts | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/packages/web-api/src/chat-stream.ts b/packages/web-api/src/chat-stream.ts
index 695100b14..4db44b6a6 100644
--- a/packages/web-api/src/chat-stream.ts
+++ b/packages/web-api/src/chat-stream.ts
@@ -89,7 +89,14 @@ export class ChatStreamer {
     if (args.token) {
       this.token = args.token;
     }
-    this.buffer += args.markdown_text;
+  
+    if (args.chunks) {
+      return await this.flushBuffer(args);
+    }
+  
+    if (args.markdown_text) {
+      this.buffer += args.markdown_text;
+    }
     if (this.buffer.length >= this.options.buffer_size) {
       return await this.flushBuffer(args);
     }
@@ -144,12 +151,13 @@ export class ChatStreamer {
       this.streamTs = response.ts;
       this.state = 'in_progress';
     }
+    const finalArgs = args?.chunks ? args : { ...args, markdown_text: this.buffer };
+
     const response = await this.client.chat.stopStream({
       token: this.token,
       channel: this.streamArgs.channel,
       ts: this.streamTs,
-      ...args,
-      markdown_text: this.buffer,
+      ...finalArgs,
     });
     this.state = 'completed';
     return response;
@@ -158,12 +166,14 @@ export class ChatStreamer {
   private async flushBuffer(
     args: Omit<ChatStartStreamArguments | ChatAppendStreamArguments, 'channel' | 'ts'>,
   ): Promise<ChatStartStreamResponse | ChatAppendStreamResponse> {
+
+    const finalArgs = args.chunks ? args : { ...args, markdown_text: this.buffer };
+
     if (!this.streamTs) {
       const response = await this.client.chat.startStream({
         ...this.streamArgs,
         token: this.token,
-        ...args,
-        markdown_text: this.buffer,
+        ...finalArgs,
       });
       this.buffer = '';
       this.streamTs = response.ts;
@@ -174,8 +184,7 @@ export class ChatStreamer {
       token: this.token,
       channel: this.streamArgs.channel,
       ts: this.streamTs,
-      ...args,
-      markdown_text: this.buffer,
+      ...finalArgs,
     });
     this.buffer = '';
     return response;

From 3ea6eecb7637e3d41ea8ccb50f4777906fef5b0e Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Tue, 20 Jan 2026 12:00:51 -0500
Subject: [PATCH 05/12] feat: add task_card and plan_blocks

---
 .../types/src/block-kit/block-elements.ts     | 15 ++++++++++++++
 packages/types/src/block-kit/blocks.ts        | 20 +++++++++++++++++++
 packages/types/src/chunk.ts                   | 13 ++----------
 3 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/packages/types/src/block-kit/block-elements.ts b/packages/types/src/block-kit/block-elements.ts
index 806561d7d..795f8bcbc 100644
--- a/packages/types/src/block-kit/block-elements.ts
+++ b/packages/types/src/block-kit/block-elements.ts
@@ -702,6 +702,21 @@ export interface URLInput extends Actionable, Dispatchable, Focusable, Placehold
   initial_value?: string;
 }
 
+export interface URLSourceElement {
+  /**
+   * @description The type of element. In this case `type` is always `url`.
+   */
+  type: 'url';
+
+  url: string;
+  
+  text: string;
+
+  icon_url?: string[];
+}
+
+
+
 /**
  * @description Allows users to run a {@link https://docs.slack.dev/tools/deno-slack-sdk/guides/creating-link-triggers/#workflow_buttons link trigger} with customizable inputs.
  * @see {@link https://docs.slack.dev/reference/block-kit/block-elements/workflow-button-element Workflow button element reference}.
diff --git a/packages/types/src/block-kit/blocks.ts b/packages/types/src/block-kit/blocks.ts
index 17d710acb..db1182920 100644
--- a/packages/types/src/block-kit/blocks.ts
+++ b/packages/types/src/block-kit/blocks.ts
@@ -22,6 +22,7 @@ import type {
   Select,
   Timepicker,
   URLInput,
+  URLSourceElement,
   WorkflowButton,
 } from './block-elements';
 import type {
@@ -64,6 +65,8 @@ export type KnownBlock =
   | RichTextBlock
   | SectionBlock
   | TableBlock
+  | TaskCardBlock
+  | PlanUpdateBlock
   | VideoBlock;
 
 /**
@@ -402,6 +405,23 @@ interface TableBlockColumnSettings {
   is_wrapped?: boolean;
 }
 
+export interface TaskCardBlock extends Block {
+  type: 'task_card';
+  task_id: string;
+  title: string;
+  details?: RichTextBlock | Record<string, unknown>;
+  output?: RichTextBlock | Record<string, unknown>;
+  sources?: (URLSourceElement | Record<string, unknown>)[]
+  status: 'pending' | 'in_progress' | 'complete' | 'error'; // pending, in_progress, complete, error
+}
+
+export interface PlanUpdateBlock extends Block {
+  type: 'plan';
+  plan_id: string;
+  title: string;
+  tasks?: (TaskCardBlock | Record<string, unknown>)[];
+}
+
 /**
  * @description Displays an embedded video player. A video block is designed to embed videos in all app surfaces (e.g.
  * link unfurls, messages, modals, App Home) — anywhere you can put blocks! To use the video block within your app, you
diff --git a/packages/types/src/chunk.ts b/packages/types/src/chunk.ts
index 6acddb06b..ebeeef1a9 100644
--- a/packages/types/src/chunk.ts
+++ b/packages/types/src/chunk.ts
@@ -1,3 +1,4 @@
+import { URLSourceElement } from "./block-kit/block-elements";
 /**
  * Base interface for streaming message chunks.
  * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
@@ -15,16 +16,6 @@ export interface MarkdownTextChunk extends Chunk {
   text: string;
 }
 
-/**
- * URL source for task update chunks.
- */
-export interface URLSource {
-  type: 'url';
-  url: string;
-  text: string;
-  icon_url?: string;
-}
-
 /**
  * An updated title of plans for task and tool calls.
  * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
@@ -45,7 +36,7 @@ export interface TaskUpdateChunk extends Chunk {
   status: 'pending' | 'in_progress' | 'complete' | 'error';
   details?: string;
   output?: string;
-  sources?: URLSource[];
+  sources?: URLSourceElement[];
 }
 
 /**

From c9522518b45a9bf3f63a8d90961b2d36030004f1 Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Tue, 20 Jan 2026 13:04:03 -0500
Subject: [PATCH 06/12] docs: add docs to task, plan, urlsourceelement
 interfaces

---
 .../types/src/block-kit/block-elements.ts     | 16 +++++-
 packages/types/src/block-kit/blocks.ts        | 52 ++++++++++++++++++-
 2 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/packages/types/src/block-kit/block-elements.ts b/packages/types/src/block-kit/block-elements.ts
index 795f8bcbc..d6b7a3c2d 100644
--- a/packages/types/src/block-kit/block-elements.ts
+++ b/packages/types/src/block-kit/block-elements.ts
@@ -702,16 +702,30 @@ export interface URLInput extends Actionable, Dispatchable, Focusable, Placehold
   initial_value?: string;
 }
 
+/**
+ *  @description A URL source element to reference in a task card block.
+ *  @see {@link https://docs.slack.dev/reference/block-kit/block-elements/url-source-element}
+ */
+
 export interface URLSourceElement {
   /**
    * @description The type of element. In this case `type` is always `url`.
    */
   type: 'url';
 
+  /**
+   * @description The URL type source.
+   */
   url: string;
-  
+
+  /**
+   * @description Display text for the URL.
+   */
   text: string;
 
+  /**
+   * @description Optional icon URL to display with the source.
+   */
   icon_url?: string[];
 }
 
diff --git a/packages/types/src/block-kit/blocks.ts b/packages/types/src/block-kit/blocks.ts
index db1182920..5c905e58a 100644
--- a/packages/types/src/block-kit/blocks.ts
+++ b/packages/types/src/block-kit/blocks.ts
@@ -405,20 +405,70 @@ interface TableBlockColumnSettings {
   is_wrapped?: boolean;
 }
 
+/** 
+ * @description A discrete action or tool call.
+ * @see https://docs.slack.dev/reference/block-kit/blocks/task-card-block/
+*/
 export interface TaskCardBlock extends Block {
+  /**
+   * @description The type of element. In this case `type` is always `task_card`.
+   */
   type: 'task_card';
+
+  /**
+   * @description ID for the task.
+   */
   task_id: string;
+
+  /**
+   * @description Title of the task in plain text.
+   */
   title: string;
+
+  /**
+   * @description Details of the task in the form of a single "rich_text" entity.
+   */
   details?: RichTextBlock | Record<string, unknown>;
+
+  /**
+   * @description Output of the task in the form of a single "rich_text" entity.
+   */
   output?: RichTextBlock | Record<string, unknown>;
+
+  /**
+   * @description List of sources used to generate a response.
+   */
   sources?: (URLSourceElement | Record<string, unknown>)[]
-  status: 'pending' | 'in_progress' | 'complete' | 'error'; // pending, in_progress, complete, error
+
+  /**
+   * @description The state of a task. Either "pending" or "in_progress" or "complete" or "error".
+   */
+  status: 'pending' | 'in_progress' | 'complete' | 'error';
 }
 
+/**
+ * @description A collection of related tasks.
+ * @see https://docs.slack.dev/reference/block-kit/blocks/plan-block/
+ */
 export interface PlanUpdateBlock extends Block {
+  /**
+   * @description The type of block. In this case `type` is always `plan`.
+   */
   type: 'plan';
+
+  /**
+   * @description ID for the plan.
+   */
   plan_id: string;
+
+  /**
+   * @description Title of the plan in plain text.
+   */
   title: string;
+
+  /**
+   * @description An array of tasks associated with this plan.
+   */
   tasks?: (TaskCardBlock | Record<string, unknown>)[];
 }
 

From e2bcf05cac7583fb7600568ae7fead22a84f684f Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Tue, 20 Jan 2026 13:05:10 -0500
Subject: [PATCH 07/12] fix: spacing in block-elements.ts

---
 packages/types/src/block-kit/block-elements.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/packages/types/src/block-kit/block-elements.ts b/packages/types/src/block-kit/block-elements.ts
index d6b7a3c2d..238000086 100644
--- a/packages/types/src/block-kit/block-elements.ts
+++ b/packages/types/src/block-kit/block-elements.ts
@@ -729,8 +729,6 @@ export interface URLSourceElement {
   icon_url?: string[];
 }
 
-
-
 /**
  * @description Allows users to run a {@link https://docs.slack.dev/tools/deno-slack-sdk/guides/creating-link-triggers/#workflow_buttons link trigger} with customizable inputs.
  * @see {@link https://docs.slack.dev/reference/block-kit/block-elements/workflow-button-element Workflow button element reference}.

From 27478ff8f1e2db921ff48b45dc80f10a3b7b5161 Mon Sep 17 00:00:00 2001
From: Ale Mercado <maria.mercado@slack-corp.com>
Date: Tue, 20 Jan 2026 13:10:19 -0500
Subject: [PATCH 08/12] test: add plan and task card tests to chat.postMessage

---
 .../web-api/test/types/methods/chat.test-d.ts | 144 +++++++++++++++++-
 1 file changed, 141 insertions(+), 3 deletions(-)

diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts
index 09916b0bb..5755f951c 100644
--- a/packages/web-api/test/types/methods/chat.test-d.ts
+++ b/packages/web-api/test/types/methods/chat.test-d.ts
@@ -42,6 +42,10 @@ expectAssignable<Parameters<typeof web.chat.appendStream>>([
         type: 'markdown_text',
         text: 'Hello world',
       },
+      {
+        type: 'plan_update',
+        title: 'Hello world',
+      },
       {
         type: 'task_update',
         id: 'task-1',
@@ -495,6 +499,131 @@ function wideBooleanTest(b: boolean) {
 wideBooleanTest(true);
 wideBooleanTest(false);
 
+// TaskCardBlock with all properties
+expectAssignable<Parameters<typeof web.chat.postMessage>>([
+  {
+    channel: 'C1234',
+    text: 'fallback',
+    blocks: [
+      {
+        type: 'task_card',
+        task_id: '000',
+        title: 'Living life well...',
+        status: 'error',
+        details: {
+          type: 'rich_text',
+          elements: [
+            {
+              type: 'rich_text_section',
+              elements: [
+                {
+                  type: 'text',
+                  text: 'Dreamt of touching grass',
+                },
+              ],
+            },
+          ],
+        },
+        sources: [
+          {
+            type: 'url',
+            text: 'An online encyclopedia',
+            url: 'https://wikipedia.org',
+          },
+        ],
+        output: {
+          type: 'rich_text',
+          elements: [
+            {
+              type: 'rich_text_section',
+              elements: [
+                {
+                  type: 'text',
+                  text: 'Good things once happened',
+                },
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+]);
+
+// TaskCardBlock with minimal required properties
+expectAssignable<Parameters<typeof web.chat.postMessage>>([
+  {
+    channel: 'C1234',
+    text: 'fallback',
+    blocks: [
+      {
+        type: 'task_card',
+        task_id: 'task-123',
+        title: 'Simple task',
+        status: 'pending',
+      },
+    ],
+  },
+]);
+
+// PlanUpdateBlock with nested TaskCardBlocks
+expectAssignable<Parameters<typeof web.chat.postMessage>>([
+  {
+    channel: 'C1234',
+    text: 'fallback',
+    blocks: [
+      {
+        type: 'plan',
+        plan_id: 'plan-001',
+        title: 'My execution plan',
+        tasks: [
+          {
+            type: 'task_card',
+            task_id: 'task-1',
+            title: 'First task',
+            status: 'complete',
+          },
+          {
+            type: 'task_card',
+            task_id: 'task-2',
+            title: 'Second task',
+            status: 'in_progress',
+            details: {
+              type: 'rich_text',
+              elements: [
+                {
+                  type: 'rich_text_section',
+                  elements: [
+                    {
+                      type: 'text',
+                      text: 'Working on this...',
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
+]);
+
+// PlanUpdateBlock with minimal required properties
+expectAssignable<Parameters<typeof web.chat.postMessage>>([
+  {
+    channel: 'C1234',
+    text: 'fallback',
+    blocks: [
+      {
+        type: 'plan',
+        plan_id: 'plan-minimal',
+        title: 'Empty plan',
+      },
+    ],
+  },
+]);
+
 // chat.scheduleMessage
 // -- sad path
 expectError(web.chat.scheduleMessage()); // lacking argument
@@ -655,12 +784,15 @@ expectAssignable<Parameters<typeof web.chat.startStream>>([
   {
     channel: 'C1234',
     thread_ts: '1234.56',
-    markdown_text: 'hello',
     chunks: [
       {
         type: 'markdown_text',
         text: 'Hello world',
       },
+      {
+        type: 'plan_update',
+        title: 'Hello world',
+      },
       {
         type: 'task_update',
         id: 'task-1',
@@ -675,12 +807,15 @@ expectAssignable<Parameters<typeof web.chat.startStream>>([
   {
     channel: 'C1234',
     thread_ts: '1234.56',
-    markdown_text: 'hello',
     chunks: [
       {
         type: 'markdown_text',
         text: 'Hello world',
       },
+      {
+        type: 'plan_update',
+        title: 'Hello world',
+      },
       {
         type: 'task_update',
         id: 'task-1',
@@ -727,12 +862,15 @@ expectAssignable<Parameters<typeof web.chat.stopStream>>([
   {
     channel: 'C1234',
     ts: '1234.56',
-    markdown_text: 'hello',
     chunks: [
       {
         type: 'markdown_text',
         text: 'Hello world',
       },
+      {
+        type: 'plan_update',
+        title: 'Hello world',
+      },
       {
         type: 'task_update',
         id: 'task-1',

From bb9247d52c8872d9e85a7d380f86d544fb8eb855 Mon Sep 17 00:00:00 2001
From: Maria Alejandra <104795114+srtaalej@users.noreply.github.com>
Date: Wed, 21 Jan 2026 12:53:52 -0500
Subject: [PATCH 09/12] Update packages/types/src/block-kit/block-elements.ts

Co-authored-by: Luke Russell <31357343+lukegalbraithrussell@users.noreply.github.com>
---
 packages/types/src/block-kit/block-elements.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/types/src/block-kit/block-elements.ts b/packages/types/src/block-kit/block-elements.ts
index 238000086..9525ab752 100644
--- a/packages/types/src/block-kit/block-elements.ts
+++ b/packages/types/src/block-kit/block-elements.ts
@@ -724,7 +724,7 @@ export interface URLSourceElement {
   text: string;
 
   /**
-   * @description Optional icon URL to display with the source.
+   * @description Icon URL to display with the source.
    */
   icon_url?: string[];
 }

From 6151d2bac229d640c7d0b7907dd602355304007c Mon Sep 17 00:00:00 2001
From: Maria Alejandra <104795114+srtaalej@users.noreply.github.com>
Date: Wed, 21 Jan 2026 12:54:09 -0500
Subject: [PATCH 10/12] Update packages/types/src/block-kit/blocks.ts

Co-authored-by: Luke Russell <31357343+lukegalbraithrussell@users.noreply.github.com>
---
 packages/types/src/block-kit/blocks.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/types/src/block-kit/blocks.ts b/packages/types/src/block-kit/blocks.ts
index 5c905e58a..b00f7c0de 100644
--- a/packages/types/src/block-kit/blocks.ts
+++ b/packages/types/src/block-kit/blocks.ts
@@ -426,7 +426,7 @@ export interface TaskCardBlock extends Block {
   title: string;
 
   /**
-   * @description Details of the task in the form of a single "rich_text" entity.
+   * @description Details of the task in the form of a single `rich_text` block.
    */
   details?: RichTextBlock | Record<string, unknown>;
 

From aeb644ad01f9b03271206f997ace9dc999370ee2 Mon Sep 17 00:00:00 2001
From: Maria Alejandra <104795114+srtaalej@users.noreply.github.com>
Date: Wed, 21 Jan 2026 12:54:44 -0500
Subject: [PATCH 11/12] Update packages/types/src/block-kit/blocks.ts

Co-authored-by: Luke Russell <31357343+lukegalbraithrussell@users.noreply.github.com>
---
 packages/types/src/block-kit/blocks.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/types/src/block-kit/blocks.ts b/packages/types/src/block-kit/blocks.ts
index b00f7c0de..99b464683 100644
--- a/packages/types/src/block-kit/blocks.ts
+++ b/packages/types/src/block-kit/blocks.ts
@@ -441,7 +441,7 @@ export interface TaskCardBlock extends Block {
   sources?: (URLSourceElement | Record<string, unknown>)[]
 
   /**
-   * @description The state of a task. Either "pending" or "in_progress" or "complete" or "error".
+   * @description The state of a task. Either `pending`, `in_progress`, `complete`, or `error`.
    */
   status: 'pending' | 'in_progress' | 'complete' | 'error';
 }

From 9981e37715ec453919cfe38ea2c42cc6ffb767f3 Mon Sep 17 00:00:00 2001
From: Maria Alejandra <104795114+srtaalej@users.noreply.github.com>
Date: Wed, 21 Jan 2026 12:54:52 -0500
Subject: [PATCH 12/12] Update packages/types/src/chunk.ts

Co-authored-by: Luke Russell <31357343+lukegalbraithrussell@users.noreply.github.com>
---
 packages/types/src/chunk.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/types/src/chunk.ts b/packages/types/src/chunk.ts
index ebeeef1a9..a60007a33 100644
--- a/packages/types/src/chunk.ts
+++ b/packages/types/src/chunk.ts
@@ -17,7 +17,7 @@ export interface MarkdownTextChunk extends Chunk {
 }
 
 /**
- * An updated title of plans for task and tool calls.
+ * Used for updating the title of a plan.
  * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
  */
 export interface PlanUpdateChunk extends Chunk {