chat 4.24.0 → 4.25.0

package/dist/index.d.ts

@@ -95,7 +95,9 @@ declare class ChannelImpl<TState = Record<string, unknown>> implements Channel<T
      */
     threads(): AsyncIterable<ThreadSummary>;
     fetchMetadata(): Promise<ChannelInfo>;
-    post(message: string | PostableMessage | ChatElement): Promise<SentMessage>;
+    post<T extends PostableObject>(message: T): Promise<T>;
+    post(message: string | AdapterPostableMessage | AsyncIterable<string> | ChatElement): Promise<SentMessage>;
+    private handlePostableObject;
     private postSingleMessage;
     postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
     schedule(message: AdapterPostableMessage | ChatElement, options: {
@@ -141,6 +143,43 @@ declare class ConsoleLogger implements Logger {
     error(message: string, ...args: unknown[]): void;
 }
 
+/**
+ * Context provided to a PostableObject after it has been posted.
+ */
+interface PostableObjectContext {
+    adapter: Adapter;
+    logger?: Logger;
+    messageId: string;
+    threadId: string;
+}
+/**
+ * Base interface for objects that can be posted to threads/channels.
+ * Examples: Plan, Poll, etc.
+ *
+ * @template TData - The data type returned by getPostData()
+ */
+interface PostableObject<TData = unknown> {
+    /** Symbol identifying this as a postable object */
+    readonly $$typeof: symbol;
+    /**
+     * Get a fallback text representation for adapters that don't support this object type.
+     * This should return a human-readable string representation.
+     */
+    getFallbackText(): string;
+    /** Get the data to send to the adapter */
+    getPostData(): TData;
+    /** Check if the adapter supports this object type */
+    isSupported(adapter: Adapter): boolean;
+    /** The kind of object - used by adapters to dispatch */
+    readonly kind: string;
+    /** Called after successful posting to bind the object to the thread */
+    onPosted(context: PostableObjectContext): void;
+}
+/**
+ * Type guard to check if a value is a PostableObject.
+ */
+declare function isPostableObject(value: unknown): value is PostableObject;
+
 /**
  * Serialized thread data for passing to external systems (e.g., workflow engines).
  */
@@ -252,7 +291,9 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     isSubscribed(): Promise<boolean>;
     subscribe(): Promise<void>;
     unsubscribe(): Promise<void>;
-    post(message: string | PostableMessage | ChatElement): Promise<SentMessage>;
+    post<T extends PostableObject>(message: T): Promise<T>;
+    post(message: string | AdapterPostableMessage | AsyncIterable<string> | ChatElement): Promise<SentMessage>;
+    private handlePostableObject;
     postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
     schedule(message: AdapterPostableMessage | ChatElement, options: {
         postAt: Date;
@@ -337,6 +378,85 @@ declare class NotImplementedError extends ChatError {
     constructor(message: string, feature?: string, cause?: unknown);
 }
 
+type PlanTaskStatus = "pending" | "in_progress" | "complete" | "error";
+interface PlanTask {
+    id: string;
+    status: PlanTaskStatus;
+    title: string;
+}
+interface PlanModel {
+    tasks: PlanModelTask[];
+    title: string;
+}
+interface PlanModelTask {
+    details?: PlanContent;
+    id: string;
+    output?: PlanContent;
+    status: PlanTaskStatus;
+    title: string;
+}
+type PlanContent = string | string[] | {
+    markdown: string;
+} | {
+    ast: Root;
+};
+interface StartPlanOptions {
+    /** Initial plan title and first task title */
+    initialMessage: PlanContent;
+}
+interface AddTaskOptions {
+    /** Task details/substeps. */
+    children?: PlanContent;
+    title: PlanContent;
+}
+type UpdateTaskInput = PlanContent | {
+    /** Task output/results. */
+    output?: PlanContent;
+    /** Optional status override. */
+    status?: PlanTaskStatus;
+};
+interface CompletePlanOptions {
+    /** Final plan title shown when completed */
+    completeMessage: PlanContent;
+}
+/**
+ * A Plan represents a task list that can be posted to a thread.
+ *
+ * Create a plan with `new Plan({ initialMessage: "..." })` and post it with `thread.post(plan)`.
+ * After posting, use methods like `addTask()`, `updateTask()`, and `complete()` to update it.
+ *
+ * @example
+ * ```typescript
+ * const plan = new Plan({ initialMessage: "Starting task..." });
+ * await thread.post(plan);
+ * await plan.addTask({ title: "Fetch data" });
+ * await plan.updateTask("Got 42 results");
+ * await plan.complete({ completeMessage: "Done!" });
+ * ```
+ */
+declare class Plan implements PostableObject<PlanModel> {
+    readonly $$typeof: symbol;
+    readonly kind = "plan";
+    private _model;
+    private _bound;
+    constructor(options: StartPlanOptions);
+    isSupported(adapter: Adapter): boolean;
+    getPostData(): PlanModel;
+    getFallbackText(): string;
+    onPosted(context: PostableObjectContext): void;
+    get id(): string;
+    get threadId(): string;
+    get title(): string;
+    get tasks(): readonly PlanTask[];
+    get currentTask(): PlanTask | null;
+    addTask(options: AddTaskOptions): Promise<PlanTask | null>;
+    updateTask(update?: UpdateTaskInput): Promise<PlanTask | null>;
+    reset(options: StartPlanOptions): Promise<PlanTask | null>;
+    complete(options: CompletePlanOptions): Promise<void>;
+    private canMutate;
+    private enqueueEdit;
+}
+
 /**
  * Represents the visibility scope of a channel.
  *
@@ -488,6 +608,16 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
     disconnect?(): Promise<void>;
     /** Edit an existing message */
     editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<TRawMessage>>;
+    /**
+     * Edit a previously posted object (Plan, Poll, etc.).
+     * If not implemented, object updates will throw PlanNotSupportedError.
+     *
+     * @param threadId - The thread containing the message
+     * @param messageId - The message ID to edit
+     * @param kind - The object kind (e.g., "plan")
+     * @param data - The object data (type depends on kind)
+     */
+    editObject?(threadId: string, messageId: string, kind: string, data: unknown): Promise<RawMessage<TRawMessage>>;
     /** Encode platform-specific data into a thread ID string */
     encodeThreadId(platformData: TThreadId): string;
     /**
@@ -633,6 +763,15 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
     postEphemeral?(threadId: string, userId: string, message: AdapterPostableMessage): Promise<EphemeralMessage<TRawMessage>>;
     /** Post a message to a thread */
     postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<TRawMessage>>;
+    /**
+     * Post a special object (Plan, Poll, etc.) as a single message.
+     * If not implemented, posting such objects will throw PlanNotSupportedError.
+     *
+     * @param threadId - The thread to post to
+     * @param kind - The object kind (e.g., "plan")
+     * @param data - The object data (type depends on kind)
+     */
+    postObject?(threadId: string, kind: string, data: unknown): Promise<RawMessage<TRawMessage>>;
     /** Remove a reaction from a message */
     removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
     /** Render formatted content to platform-specific string */
@@ -920,6 +1059,7 @@ interface Postable<TState = Record<string, unknown>, TRawMessage = unknown> {
     /**
      * Post a message.
      */
+    post<T extends PostableObject>(message: T): Promise<T>;
     post(message: string | PostableMessage | ChatElement): Promise<SentMessage<TRawMessage>>;
     /**
      * Post an ephemeral message visible only to a specific user.
@@ -1097,8 +1237,15 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
      * // Stream from AI SDK
      * const result = await agent.stream({ prompt: message.text });
      * await thread.post(result.textStream);
+     *
+     * // Plan with live updates
+     * const plan = new Plan({ initialMessage: "Working..." });
+     * await thread.post(plan);
+     * await plan.addTask({ title: "Step 1" });
+     * await plan.complete({ completeMessage: "Done!" });
      * ```
      */
+    post<T extends PostableObject>(message: T): Promise<T>;
     post(message: string | PostableMessage | ChatElement): Promise<SentMessage<TRawMessage>>;
     /**
      * Post an ephemeral message visible only to a specific user.
@@ -1171,6 +1318,7 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
      */
     unsubscribe(): Promise<void>;
 }
+
 interface ThreadInfo {
     channelId: string;
     channelName?: string;
@@ -1358,7 +1506,7 @@ type AdapterPostableMessage = string | PostableRaw | PostableMarkdown | Postable
  * - `AsyncIterable<string>` - Streaming text (e.g., from AI SDK's textStream)
  * - `AsyncIterable<string | StreamEvent>` - AI SDK fullStream (auto-detected, extracts text with step separators)
  */
-type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChunk | StreamEvent>;
+type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChunk | StreamEvent> | PostableObject;
 /**
  * Duck-typed stream event compatible with AI SDK's `fullStream`.
  * - `text-delta` events are extracted as text output.
@@ -2733,6 +2881,13 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
  */
 declare function fromFullStream(stream: AsyncIterable<unknown>): AsyncIterable<string | StreamChunk>;
 
+interface StreamingMarkdownRendererOptions {
+    /**
+     * Wrap confirmed table blocks in code fences for append-only consumers that
+     * cannot render markdown tables while a stream is in flight.
+     */
+    wrapTablesForAppend?: boolean;
+}
 /**
  * A streaming markdown renderer that buffers potential table headers
  * until confirmed by a separator line, preventing tables from flashing
@@ -2750,6 +2905,8 @@ declare class StreamingMarkdownRenderer {
     private fenceToggles;
     /** Incomplete trailing line buffer for incremental fence tracking. */
     private incompleteLine;
+    private readonly options;
+    constructor(options?: StreamingMarkdownRendererOptions);
     /** Append a chunk from the LLM stream. */
     push(chunk: string): void;
     /** O(1) check if accumulated text is inside an unclosed code fence. */
@@ -2766,9 +2923,10 @@ declare class StreamingMarkdownRenderer {
      * Get text safe for append-only streaming (e.g. Slack native streaming).
      *
      * - Holds back unconfirmed table headers until separator arrives.
-     * - Wraps confirmed tables in code fences so pipes render as literal
-     *   text (not broken mrkdwn). The code fence is left OPEN while
-     *   the table is still streaming, keeping output monotonic for deltas.
+     * - Optionally wraps confirmed tables in code fences so pipes render as
+     *   literal text on append-only surfaces that lack native table support.
+     *   The code fence is left OPEN while the table is still streaming,
+     *   keeping output monotonic for deltas.
      * - Holds back unclosed inline markers (**, *, ~~, `, [).
      * - The final editMessage replaces everything with properly formatted text.
      */
@@ -2777,6 +2935,7 @@ declare class StreamingMarkdownRenderer {
     getText(): string;
     /** Signal stream end. Flushes held-back lines. Returns final render. */
     finish(): string;
+    private formatAppendOnlyText;
 }
 
 /**
@@ -3222,4 +3381,4 @@ declare const Select: SelectComponent;
 declare const SelectOption: SelectOptionComponent;
 declare const TextInput: TextInputComponent;
 
-export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, type ChannelVisibility, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, type ConcurrencyConfig, type ConcurrencyStrategy, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LockScope, type LockScopeContext, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageContext, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, type QueueEntry, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };
+export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AddTaskOptions, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, type ChannelVisibility, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, type CompletePlanOptions, type ConcurrencyConfig, type ConcurrencyStrategy, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LockScope, type LockScopeContext, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageContext, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, Plan, type PlanContent, type PlanModel, type PlanModelTask, type PlanTask, type PlanTaskStatus, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableObject, type PostableObjectContext, type PostableRaw, type QueueEntry, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StartPlanOptions, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type UpdateTaskInput, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isPostableObject, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };

package/dist/index.js

@@ -380,6 +380,27 @@ var Message = class _Message {
   }
 };
 
+// src/postable-object.ts
+var POSTABLE_OBJECT = /* @__PURE__ */ Symbol.for("chat.postable");
+function isPostableObject(value) {
+  return typeof value === "object" && value !== null && value.$$typeof === POSTABLE_OBJECT;
+}
+async function postPostableObject(obj, adapter, threadId, postFn, logger) {
+  const context = (raw) => ({
+    adapter,
+    logger,
+    messageId: raw.id,
+    threadId: raw.threadId ?? threadId
+  });
+  if (obj.isSupported(adapter) && adapter.postObject) {
+    const raw = await adapter.postObject(threadId, obj.kind, obj.getPostData());
+    obj.onPosted(context(raw));
+  } else {
+    const raw = await postFn(threadId, obj.getFallbackText());
+    obj.onPosted(context(raw));
+  }
+}
+
 // src/errors.ts
 var ChatError = class extends Error {
   code;
@@ -605,6 +626,10 @@ var ChannelImpl = class _ChannelImpl {
     };
   }
   async post(message) {
+    if (isPostableObject(message)) {
+      await this.handlePostableObject(message);
+      return message;
+    }
     if (isAsyncIterable(message)) {
       let accumulated = "";
       for await (const chunk of fromFullStream(message)) {
@@ -624,6 +649,14 @@ var ChannelImpl = class _ChannelImpl {
     }
     return this.postSingleMessage(postable);
   }
+  async handlePostableObject(obj) {
+    await postPostableObject(
+      obj,
+      this.adapter,
+      this.id,
+      (threadId, message) => this.adapter.postChannelMessage ? this.adapter.postChannelMessage(threadId, message) : this.adapter.postMessage(threadId, message)
+    );
+  }
   async postSingleMessage(postable) {
     const rawMessage = this.adapter.postChannelMessage ? await this.adapter.postChannelMessage(this.id, postable) : await this.adapter.postMessage(this.id, postable);
     const sent = this.createSentMessage(
@@ -877,6 +910,12 @@ var StreamingMarkdownRenderer = class {
   fenceToggles = 0;
   /** Incomplete trailing line buffer for incremental fence tracking. */
   incompleteLine = "";
+  options;
+  constructor(options = {}) {
+    this.options = {
+      wrapTablesForAppend: options.wrapTablesForAppend ?? true
+    };
+  }
   /** Append a chunk from the LLM stream. */
   push(chunk) {
     this.accumulated += chunk;
@@ -928,30 +967,31 @@ var StreamingMarkdownRenderer = class {
    * Get text safe for append-only streaming (e.g. Slack native streaming).
    *
    * - Holds back unconfirmed table headers until separator arrives.
-   * - Wraps confirmed tables in code fences so pipes render as literal
-   *   text (not broken mrkdwn). The code fence is left OPEN while
-   *   the table is still streaming, keeping output monotonic for deltas.
+   * - Optionally wraps confirmed tables in code fences so pipes render as
+   *   literal text on append-only surfaces that lack native table support.
+   *   The code fence is left OPEN while the table is still streaming,
+   *   keeping output monotonic for deltas.
    * - Holds back unclosed inline markers (**, *, ~~, `, [).
    * - The final editMessage replaces everything with properly formatted text.
    */
   getCommittableText() {
     if (this.finished) {
-      return wrapTablesForAppend(this.accumulated, true);
+      return this.formatAppendOnlyText(this.accumulated, true);
     }
     let text2 = this.accumulated;
     if (text2.length > 0 && !text2.endsWith("\n")) {
       const lastNewline = text2.lastIndexOf("\n");
       const withoutIncompleteLine = lastNewline >= 0 ? text2.slice(0, lastNewline + 1) : "";
       if (isInsideCodeFence(withoutIncompleteLine)) {
-        return wrapTablesForAppend(text2);
+        return this.formatAppendOnlyText(text2);
       }
       text2 = withoutIncompleteLine;
     }
     if (isInsideCodeFence(text2)) {
-      return wrapTablesForAppend(text2);
+      return this.formatAppendOnlyText(text2);
     }
     const committed = getCommittablePrefix(text2);
-    const wrapped = wrapTablesForAppend(committed);
+    const wrapped = this.formatAppendOnlyText(committed);
     if (isInsideCodeFence(wrapped)) {
       return wrapped;
     }
@@ -967,6 +1007,12 @@ var StreamingMarkdownRenderer = class {
     this.dirty = true;
     return this.render();
   }
+  formatAppendOnlyText(text2, closeFences = false) {
+    if (!this.options.wrapTablesForAppend) {
+      return text2;
+    }
+    return wrapTablesForAppend(text2, closeFences);
+  }
 };
 var INLINE_MARKER_CHARS = /* @__PURE__ */ new Set(["*", "~", "`", "["]);
 function isClean(text2) {
@@ -1308,6 +1354,10 @@ var ThreadImpl = class _ThreadImpl {
     await this._stateAdapter.unsubscribe(this.id);
   }
   async post(message) {
+    if (isPostableObject(message)) {
+      await this.handlePostableObject(message);
+      return message;
+    }
     if (isAsyncIterable2(message)) {
       return this.handleStream(message);
     }
@@ -1330,6 +1380,15 @@ var ThreadImpl = class _ThreadImpl {
     }
     return result;
   }
+  async handlePostableObject(obj) {
+    await postPostableObject(
+      obj,
+      this.adapter,
+      this.id,
+      (threadId, message) => this.adapter.postMessage(threadId, message),
+      this._logger
+    );
+  }
   async postEphemeral(user, message, options) {
     const { fallbackToDM } = options;
     const userId = typeof user === "string" ? user : user.userId;
@@ -3311,6 +3370,220 @@ var Chat = class {
   }
 };
 
+// src/plan.ts
+function contentToPlainText(content) {
+  if (!content) {
+    return "";
+  }
+  if (Array.isArray(content)) {
+    return content.join(" ").trim();
+  }
+  if (typeof content === "string") {
+    return content;
+  }
+  if ("markdown" in content) {
+    return toPlainText(parseMarkdown(content.markdown));
+  }
+  if ("ast" in content) {
+    return toPlainText(content.ast);
+  }
+  return "";
+}
+var Plan = class {
+  $$typeof = POSTABLE_OBJECT;
+  kind = "plan";
+  _model;
+  _bound = null;
+  constructor(options) {
+    const title = contentToPlainText(options.initialMessage) || "Plan";
+    const firstTask = {
+      id: crypto.randomUUID(),
+      title,
+      status: "in_progress"
+    };
+    this._model = { title, tasks: [firstTask] };
+  }
+  isSupported(adapter) {
+    return !!adapter.postObject && !!adapter.editObject;
+  }
+  getPostData() {
+    return this._model;
+  }
+  getFallbackText() {
+    const lines = [];
+    lines.push(`\u{1F4CB} ${this._model.title || "Plan"}`);
+    for (const task of this._model.tasks) {
+      const statusIcons = {
+        complete: "\u2705",
+        in_progress: "\u{1F504}",
+        error: "\u274C"
+      };
+      const statusIcon = statusIcons[task.status] ?? "\u2B1C";
+      lines.push(`${statusIcon} ${task.title}`);
+    }
+    return lines.join("\n");
+  }
+  onPosted(context) {
+    this._bound = {
+      adapter: context.adapter,
+      fallback: !this.isSupported(context.adapter),
+      logger: context.logger,
+      messageId: context.messageId,
+      threadId: context.threadId,
+      updateChain: Promise.resolve()
+    };
+  }
+  get id() {
+    return this._bound?.messageId ?? "";
+  }
+  get threadId() {
+    return this._bound?.threadId ?? "";
+  }
+  get title() {
+    return this._model.title;
+  }
+  get tasks() {
+    return this._model.tasks.map((t) => ({
+      id: t.id,
+      title: t.title,
+      status: t.status
+    }));
+  }
+  get currentTask() {
+    let current;
+    for (let i = this._model.tasks.length - 1; i >= 0; i--) {
+      if (this._model.tasks[i].status === "in_progress") {
+        current = this._model.tasks[i];
+        break;
+      }
+    }
+    current ??= this._model.tasks.at(-1);
+    if (!current) {
+      return null;
+    }
+    return { id: current.id, title: current.title, status: current.status };
+  }
+  async addTask(options) {
+    if (!this.canMutate()) {
+      return null;
+    }
+    const title = contentToPlainText(options.title) || "Task";
+    for (const task of this._model.tasks) {
+      if (task.status === "in_progress") {
+        task.status = "complete";
+      }
+    }
+    const nextTask = {
+      id: crypto.randomUUID(),
+      title,
+      status: "in_progress",
+      details: options.children
+    };
+    this._model.tasks.push(nextTask);
+    this._model.title = title;
+    await this.enqueueEdit();
+    return { id: nextTask.id, title: nextTask.title, status: nextTask.status };
+  }
+  async updateTask(update) {
+    if (!this.canMutate()) {
+      return null;
+    }
+    let current;
+    for (let i = this._model.tasks.length - 1; i >= 0; i--) {
+      if (this._model.tasks[i].status === "in_progress") {
+        current = this._model.tasks[i];
+        break;
+      }
+    }
+    current ??= this._model.tasks.at(-1);
+    if (!current) {
+      return null;
+    }
+    if (update !== void 0) {
+      if (typeof update === "object" && update !== null && "output" in update) {
+        if (update.output !== void 0) {
+          current.output = update.output;
+        }
+        if (update.status) {
+          current.status = update.status;
+        }
+      } else {
+        current.output = update;
+      }
+    }
+    await this.enqueueEdit();
+    return { id: current.id, title: current.title, status: current.status };
+  }
+  async reset(options) {
+    if (!this.canMutate()) {
+      return null;
+    }
+    const title = contentToPlainText(options.initialMessage) || "Plan";
+    const firstTask = {
+      id: crypto.randomUUID(),
+      title,
+      status: "in_progress"
+    };
+    this._model = { title, tasks: [firstTask] };
+    await this.enqueueEdit();
+    return {
+      id: firstTask.id,
+      title: firstTask.title,
+      status: firstTask.status
+    };
+  }
+  async complete(options) {
+    if (!this.canMutate()) {
+      return;
+    }
+    for (const task of this._model.tasks) {
+      if (task.status === "in_progress") {
+        task.status = "complete";
+      }
+    }
+    this._model.title = contentToPlainText(options.completeMessage) || this._model.title;
+    await this.enqueueEdit();
+  }
+  canMutate() {
+    return !!this._bound;
+  }
+  enqueueEdit() {
+    if (!this._bound) {
+      return Promise.resolve();
+    }
+    const bound = this._bound;
+    const doEdit = async () => {
+      if (bound.fallback) {
+        await bound.adapter.editMessage(
+          bound.threadId,
+          bound.messageId,
+          this.getFallbackText()
+        );
+      } else {
+        const editObject = bound.adapter.editObject;
+        if (!editObject) {
+          return;
+        }
+        await editObject.call(
+          bound.adapter,
+          bound.threadId,
+          bound.messageId,
+          this.kind,
+          this._model
+        );
+      }
+    };
+    const chained = bound.updateChain.then(doEdit, doEdit);
+    bound.updateChain = chained.then(
+      () => void 0,
+      (err) => {
+        bound.logger?.warn("Failed to edit plan", err);
+      }
+    );
+    return chained;
+  }
+};
+
 // src/emoji.ts
 var emojiRegistry = /* @__PURE__ */ new Map();
 function getEmoji(name) {
@@ -3749,6 +4022,7 @@ export {
   MessageHistoryCache,
   Modal2 as Modal,
   NotImplementedError,
+  Plan,
   RadioSelect2 as RadioSelect,
   RateLimitError,
   Section2 as Section,
@@ -3787,6 +4061,7 @@ export {
   isListNode,
   isModalElement2 as isModalElement,
   isParagraphNode,
+  isPostableObject,
   isStrongNode,
   isTableCellNode,
   isTableNode,

package/docs/guides/slack-nextjs.mdx

@@ -87,6 +87,8 @@ After creating the app:
 1. Go to **OAuth & Permissions**, click **Install to Workspace**, and copy the **Bot User OAuth Token** (`xoxb-...`) — you'll need this as `SLACK_BOT_TOKEN`
 2. Go to **Basic Information** → **App Credentials** and copy the **Signing Secret** — you'll need this as `SLACK_SIGNING_SECRET`
 
+If you're distributing the app across multiple workspaces via OAuth instead of installing it to one workspace, configure `clientId` and `clientSecret` on the Slack adapter and pass the same redirect URI used during the authorize step into `handleOAuthCallback(request, { redirectUri })` in your callback route.
+
 ## Configure environment variables
 
 Create a `.env.local` file in your project root:

package/package.json

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