chat 4.26.0 → 4.28.1

package/dist/index.d.ts

@@ -1,27 +1,30 @@
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 import { Root, List, Content, Blockquote, Code, Emphasis, InlineCode, Delete, Link, ListItem, Paragraph, Strong, TableCell, Table as Table$1, TableRow, Text } from 'mdast';
-export { Blockquote, Code, Content, Delete, Emphasis, InlineCode, Link, List, ListItem, Table as MdastTable, Paragraph, Root, Strong, TableCell, TableRow, Text } from 'mdast';
-import { C as ChatElement, a as CardElement, M as ModalElement, b as CardChild, A as ActionsComponent, B as ButtonComponent, c as CardComponent, d as cardChildToFallbackText$1, e as CardLinkComponent, T as TextComponent, D as DividerComponent, F as FieldComponent, f as FieldsComponent, g as fromReactElement$1, I as ImageComponent, i as isCardElement$1, h as isJSX$1, L as LinkButtonComponent, S as SectionComponent, j as Table$2, t as toCardElement$1, k as toModalElement$1, l as fromReactModalElement$1, m as isModalElement$1, n as ModalComponent, R as RadioSelectComponent, o as SelectComponent, p as SelectOptionComponent, q as TextInputComponent } from './jsx-runtime-DxATbnrP.js';
-export { r as ActionsElement, s as ButtonElement, u as ButtonOptions, V as ButtonProps, v as ButtonStyle, W as CardJSXElement, X as CardJSXProps, Y as CardLinkProps, w as CardOptions, Z as CardProps, _ as ContainerProps, x as DividerElement, $ as DividerProps, y as FieldElement, a0 as FieldProps, z as FieldsElement, E as ImageElement, a1 as ImageProps, G as LinkButtonElement, H as LinkButtonOptions, a2 as LinkButtonProps, J as LinkElement, a8 as ModalChild, a9 as ModalOptions, a3 as ModalProps, aa as RadioSelectElement, ab as RadioSelectOptions, K as SectionElement, ac as SelectElement, ad as SelectOptionElement, a4 as SelectOptionProps, ae as SelectOptions, a5 as SelectProps, N as TableAlignment, O as TableElement, P as TableOptions, Q as TextElement, af as TextInputElement, ag as TextInputOptions, a6 as TextInputProps, a7 as TextProps, U as TextStyle } from './jsx-runtime-DxATbnrP.js';
+export { Blockquote, Code, Content, Delete, Emphasis, InlineCode, Link, List, ListItem, Table as MdastTable, Nodes, Paragraph, Root, Strong, TableCell, TableRow, Text } from 'mdast';
+import { C as ChatElement, a as CardElement, M as ModalElement, S as SelectOptionElement, b as CardChild, A as ActionsComponent, B as ButtonComponent, c as CardComponent, d as cardChildToFallbackText$1, e as CardLinkComponent, T as TextComponent, D as DividerComponent, F as FieldComponent, f as FieldsComponent, g as fromReactElement$1, I as ImageComponent, i as isCardElement$1, h as isJSX$1, L as LinkButtonComponent, j as SectionComponent, k as Table$2, t as toCardElement$1, l as toModalElement$1, m as fromReactModalElement$1, n as isModalElement$1, E as ExternalSelectComponent, o as ModalComponent, R as RadioSelectComponent, p as SelectComponent, q as SelectOptionComponent, r as TextInputComponent } from './jsx-runtime-DxGwoLu2.js';
+export { s as ActionsElement, u as ButtonElement, v as ButtonOptions, X as ButtonProps, w as ButtonStyle, Y as CardJSXElement, Z as CardJSXProps, _ as CardLinkProps, x as CardOptions, $ as CardProps, a0 as ContainerProps, y as DividerElement, a1 as DividerProps, ab as ExternalSelectElement, ac as ExternalSelectOptions, a2 as ExternalSelectProps, z as FieldElement, a3 as FieldProps, G as FieldsElement, H as ImageElement, a4 as ImageProps, J as LinkButtonElement, K as LinkButtonOptions, a5 as LinkButtonProps, N as LinkElement, ad as ModalChild, ae as ModalOptions, a6 as ModalProps, af as RadioSelectElement, ag as RadioSelectOptions, O as SectionElement, ah as SelectElement, a7 as SelectOptionProps, ai as SelectOptions, a8 as SelectProps, P as TableAlignment, Q as TableElement, U as TableOptions, V as TextElement, aj as TextInputElement, ak as TextInputOptions, a9 as TextInputProps, aa as TextProps, W as TextStyle } from './jsx-runtime-DxGwoLu2.js';
 
-interface MessageHistoryConfig {
+interface ThreadHistoryConfig {
     /** Maximum messages to keep per thread (default: 100) */
     maxMessages?: number;
     /** TTL for cached history in milliseconds (default: 7 days) */
     ttlMs?: number;
 }
 /**
- * Persistent message history cache backed by the StateAdapter.
+ * Persistent per-thread history cache backed by the StateAdapter.
  *
- * Used by adapters that lack server-side message history APIs (e.g., WhatsApp, Telegram).
- * Messages are atomically appended via `state.appendToList()`, which is safe
- * without holding a thread lock.
+ * Used by adapters that lack server-side message history APIs (e.g. WhatsApp,
+ * Telegram). Messages are atomically appended via `state.appendToList()`,
+ * which is safe without holding a thread lock.
+ *
+ * Distinct from the cross-platform per-user {@link TranscriptsApi} (see
+ * `transcripts.ts`) — this cache is keyed by thread, not user.
  */
-declare class MessageHistoryCache {
+declare class ThreadHistoryCache {
     private readonly state;
     private readonly maxMessages;
     private readonly ttlMs;
-    constructor(state: StateAdapter, config?: MessageHistoryConfig);
+    constructor(state: StateAdapter, config?: ThreadHistoryConfig);
     /**
      * Atomically append a message to the history for a thread.
      * Trims to maxMessages (keeps newest) and refreshes TTL.
@@ -54,8 +57,8 @@ interface ChannelImplConfigWithAdapter {
     channelVisibility?: ChannelVisibility;
     id: string;
     isDM?: boolean;
-    messageHistory?: MessageHistoryCache;
     stateAdapter: StateAdapter;
+    threadHistory?: ThreadHistoryCache;
 }
 /**
  * Config for creating a ChannelImpl with lazy adapter resolution.
@@ -75,7 +78,7 @@ declare class ChannelImpl<TState = Record<string, unknown>> implements Channel<T
     private readonly _adapterName?;
     private _stateAdapterInstance?;
     private _name;
-    private readonly _messageHistory?;
+    private readonly _threadHistory?;
     constructor(config: ChannelImplConfig);
     get adapter(): Adapter;
     private get _stateAdapter();
@@ -103,6 +106,7 @@ declare class ChannelImpl<TState = Record<string, unknown>> implements Channel<T
     schedule(message: AdapterPostableMessage | ChatElement, options: {
         postAt: Date;
     }): Promise<ScheduledMessage>;
+    private processCallbackUrls;
     startTyping(status?: string): Promise<void>;
     mentionUser(userId: string): string;
     toJSON(): SerializedChannel;
@@ -206,9 +210,9 @@ interface ThreadImplConfigWithAdapter {
     isDM?: boolean;
     isSubscribedContext?: boolean;
     logger?: Logger;
-    messageHistory?: MessageHistoryCache;
     stateAdapter: StateAdapter;
     streamingUpdateIntervalMs?: number;
+    threadHistory?: ThreadHistoryCache;
 }
 /**
  * Config for creating a ThreadImpl with lazy adapter resolution.
@@ -249,8 +253,8 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     private readonly _fallbackStreamingPlaceholderText;
     /** Cached channel instance */
     private _channel?;
-    /** Message history cache (set only for adapters with persistMessageHistory) */
-    private readonly _messageHistory?;
+    /** Thread history cache (set only for adapters with persistThreadHistory) */
+    private readonly _threadHistory?;
     private readonly _logger?;
     constructor(config: ThreadImplConfig);
     /**
@@ -288,6 +292,7 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
      */
     get messages(): AsyncIterable<Message>;
     get allMessages(): AsyncIterable<Message>;
+    getParticipants(): Promise<Author[]>;
     isSubscribed(): Promise<boolean>;
     subscribe(): Promise<void>;
     unsubscribe(): Promise<void>;
@@ -295,15 +300,23 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     post(message: string | AdapterPostableMessage | AsyncIterable<string> | ChatElement): Promise<SentMessage>;
     private handlePostableObject;
     postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
+    private processCallbackUrls;
     schedule(message: AdapterPostableMessage | ChatElement, options: {
         postAt: Date;
     }): Promise<ScheduledMessage>;
     /**
      * Handle streaming from an AsyncIterable.
      * Normalizes the stream (supports both textStream and fullStream from AI SDK),
-     * then uses adapter's native streaming if available, otherwise falls back to post+edit.
+     * then uses the adapter's stream implementation if available, otherwise falls back to post+edit.
      */
     private handleStream;
+    /**
+     * Slack payloads carry the workspace ID in a few different shapes depending on
+     * the webhook type:
+     * - Message events: `team_id` or `team` as a string
+     * - `block_actions` payloads: `team.id` (object), with `user.team_id` as a fallback
+     */
+    private extractSlackRecipientTeamId;
     startTyping(status?: string): Promise<void>;
     /**
      * Fallback streaming implementation using post + edit.
@@ -410,6 +423,8 @@ interface AddTaskOptions {
     title: PlanContent;
 }
 type UpdateTaskInput = PlanContent | {
+    /** Task ID to update. If omitted, updates the last in_progress task. */
+    id?: string;
     /** Task output/results. */
     output?: PlanContent;
     /** Optional status override. */
@@ -502,6 +517,14 @@ interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string,
      * wait until some real text has been streamed before creating the message.
      */
     fallbackStreamingPlaceholderText?: string | null;
+    /**
+     * Resolves a stable cross-platform user key from inbound messages.
+     *
+     * Required when `transcripts` is configured. Called once per inbound
+     * message during dispatch; the result is attached to the Message
+     * instance as `message.userKey` for handlers to use.
+     */
+    identity?: IdentityResolver;
     /**
      * Lock scope determines which messages contend for the same lock.
      *
@@ -519,13 +542,12 @@ interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string,
      */
     logger?: Logger | LogLevel;
     /**
-     * Configuration for persistent message history.
-     * Only used by adapters that set `persistMessageHistory: true`.
+     * @deprecated Renamed to {@link ChatConfig.threadHistory}. Both fields are
+     * read for backwards compatibility; `threadHistory` takes precedence when
+     * both are set.
      */
     messageHistory?: {
-        /** Maximum messages to store per thread (default: 100) */
         maxMessages?: number;
-        /** TTL for cached history in milliseconds (default: 7 days) */
         ttlMs?: number;
     };
     /**
@@ -549,6 +571,28 @@ interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string,
      * Defaults to 500ms. Lower values provide smoother updates but may hit rate limits.
      */
     streamingUpdateIntervalMs?: number;
+    /**
+     * Configuration for persistent per-thread message history backfill.
+     *
+     * Only used by adapters that set `persistThreadHistory: true` (e.g.
+     * Telegram, WhatsApp). Distinct from `transcripts` (the cross-platform
+     * per-user Transcripts API).
+     */
+    threadHistory?: {
+        /** Maximum messages to store per thread (default: 100) */
+        maxMessages?: number;
+        /** TTL for cached history in milliseconds (default: 7 days) */
+        ttlMs?: number;
+    };
+    /**
+     * Cross-platform per-user message persistence.
+     *
+     * When set, `chat.transcripts` is available for append/list/count/delete
+     * keyed by a resolved cross-platform user key.
+     *
+     * Requires `identity` to also be set; the constructor throws otherwise.
+     */
+    transcripts?: TranscriptsConfig;
     /** Default bot username across all adapters */
     userName: string;
 }
@@ -671,6 +715,7 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * ```
      */
     fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<TRawMessage>>;
+    fetchSubject?(raw: TRawMessage): Promise<MessageSubject | null>;
     /** Fetch thread metadata */
     fetchThread(threadId: string): Promise<ThreadInfo>;
     /**
@@ -683,6 +728,14 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * @returns The channel visibility scope
      */
     getChannelVisibility?(threadId: string): ChannelVisibility;
+    /**
+     * Look up user information by user ID.
+     * Optional — not all platforms support this.
+     *
+     * @param userId - Platform-specific user ID
+     * @returns User info, or null if user not found
+     */
+    getUser?(userId: string): Promise<UserInfo | null>;
     /** Handle incoming webhook request */
     handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
     /** Called when Chat instance is created (internal use) */
@@ -741,10 +794,17 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
     /** Parse platform message format to normalized format */
     parseMessage(raw: TRawMessage): Message<TRawMessage>;
     /**
-     * When true, the SDK persists message history in the state adapter for this platform.
-     * Use this for platforms that lack server-side message history APIs (e.g., WhatsApp, Telegram).
+     * @deprecated Renamed to {@link Adapter.persistThreadHistory}. Both flags
+     * are read for backwards compatibility; either being `true` enables
+     * persistence.
      */
     readonly persistMessageHistory?: boolean;
+    /**
+     * When true, the SDK persists per-thread message history in the state
+     * adapter for this platform. Use for platforms that lack server-side
+     * message history APIs (e.g. WhatsApp, Telegram).
+     */
+    readonly persistThreadHistory?: boolean;
     /**
      * Post a message to channel top-level (not in a thread).
      */
@@ -772,6 +832,12 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * @param data - The object data (type depends on kind)
      */
     postObject?(threadId: string, kind: string, data: unknown): Promise<RawMessage<TRawMessage>>;
+    /**
+     * Reconstruct fetchData on an attachment after deserialization.
+     * Called during message rehydration for queue/debounce strategies.
+     * Uses fetchMetadata and adapter auth context to rebuild the download closure.
+     */
+    rehydrateAttachment?(attachment: Attachment): Attachment;
     /** Remove a reaction from a message */
     removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
     /** Render formatted content to platform-specific string */
@@ -828,6 +894,7 @@ interface MarkdownTextChunk {
     type: "markdown_text";
 }
 interface TaskUpdateChunk {
+    details?: string;
     id: string;
     output?: string;
     status: "pending" | "in_progress" | "complete" | "error";
@@ -891,7 +958,7 @@ interface ChatInstance {
      * @param message - Either a parsed message, or a factory function for lazy async parsing
      * @param options - Webhook options including waitUntil
      */
-    processMessage(adapter: Adapter, threadId: string, message: Message | (() => Promise<Message>), options?: WebhookOptions): void;
+    processMessage(adapter: Adapter, threadId: string, message: Message | (() => Promise<Message>), options?: WebhookOptions): Promise<void>;
     /**
      * Process a modal close event from an adapter.
      *
@@ -908,6 +975,11 @@ interface ChatInstance {
      * @param options - Webhook options
      */
     processModalSubmit(event: Omit<ModalSubmitEvent, "relatedThread" | "relatedMessage" | "relatedChannel">, contextId?: string, options?: WebhookOptions): Promise<ModalResponse | undefined>;
+    /**
+     * Process an interactive options load event from an adapter.
+     * Returns normalized select options for the adapter to render.
+     */
+    processOptionsLoad(event: OptionsLoadEvent, options?: WebhookOptions): Promise<OptionsLoadResult | undefined>;
     /**
      * Process an incoming reaction event from an adapter.
      * Handles waitUntil registration and error catching internally.
@@ -929,6 +1001,12 @@ interface ChatInstance {
         adapter: Adapter;
         channelId: string;
     }, options: WebhookOptions | undefined): void;
+    /**
+     * Cross-platform per-user transcript store. Throws on access when
+     * `transcripts` is not configured on the Chat instance — callers should
+     * check `ChatConfig.transcripts` if they need a no-throw guard.
+     */
+    readonly transcripts: TranscriptsApi;
 }
 /** Lock scope determines which messages contend for the same lock. */
 type LockScope = "thread" | "channel";
@@ -1190,6 +1268,40 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
      * Used internally for reconstructing messages from serialized data.
      */
     createSentMessageFromMessage(message: Message<TRawMessage>): SentMessage<TRawMessage>;
+    /**
+     * Get the unique human participants in this thread.
+     *
+     * Scans all messages in the thread and returns deduplicated authors,
+     * excluding the bot itself. Useful for deciding whether to subscribe
+     * based on how many humans are participating — subscribe when it's a
+     * 1:1 conversation, unsubscribe when others join so humans can talk
+     * without the bot replying to every message.
+     *
+     * @returns Array of unique non-bot authors
+     *
+     * @example
+     * ```typescript
+     * // Subscribe only when one person is talking to the bot
+     * bot.onNewMention(async (thread, message) => {
+     *   const participants = await thread.getParticipants();
+     *   if (participants.length === 1) {
+     *     await thread.subscribe();
+     *     await thread.post("I'm here to help!");
+     *   }
+     * });
+     *
+     * // Unsubscribe when the thread becomes a group conversation
+     * bot.onSubscribedMessage(async (thread, message) => {
+     *   const participants = await thread.getParticipants();
+     *   if (participants.length > 1) {
+     *     await thread.unsubscribe();
+     *     return;
+     *   }
+     *   await thread.post("Still here to help!");
+     * });
+     * ```
+     */
+    getParticipants(): Promise<Author[]>;
     /**
      * Check if this thread is currently subscribed.
      *
@@ -1238,6 +1350,13 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
      * const result = await agent.stream({ prompt: message.text });
      * await thread.post(result.textStream);
      *
+     * // Stream with options via StreamingPlan PostableObject
+     * const stream = new StreamingPlan(result.fullStream, {
+     *   groupTasks: "plan",
+     *   endWith: [feedbackBlocks],
+     * });
+     * await thread.post(stream);
+     *
      * // Plan with live updates
      * const plan = new Plan({ initialMessage: "Working..." });
      * await thread.post(plan);
@@ -1319,6 +1438,24 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
     unsubscribe(): Promise<void>;
 }
 
+interface MessageSubject {
+    assignee?: {
+        id: string;
+        name: string;
+    };
+    author?: {
+        id: string;
+        name: string;
+    };
+    description?: string;
+    id: string;
+    labels?: string[];
+    raw: unknown;
+    status?: string;
+    title?: string;
+    type: string;
+    url?: string;
+}
 interface ThreadInfo {
     channelId: string;
     channelName?: string;
@@ -1425,6 +1562,21 @@ interface Author {
     /** Username/handle for @-mentions */
     userName: string;
 }
+/** User information returned by adapter.getUser() */
+interface UserInfo {
+    /** URL to the user's avatar/profile image */
+    avatarUrl?: string;
+    /** User's email address (requires appropriate scopes on some platforms) */
+    email?: string;
+    /** User's display name / full name */
+    fullName: string;
+    /** Whether the user is a bot */
+    isBot: boolean;
+    /** Platform-specific user ID */
+    userId: string;
+    /** Username/handle */
+    userName: string;
+}
 interface MessageMetadata {
     /** When the message was sent */
     dateSent: Date;
@@ -1433,7 +1585,7 @@ interface MessageMetadata {
     /** When the message was last edited */
     editedAt?: Date;
 }
-interface SentMessage<TRawMessage = unknown> extends Message<TRawMessage> {
+interface SentMessage<TRawMessage = unknown> extends Omit<Message<TRawMessage>, "subject"> {
     /** Add a reaction to this message */
     addReaction(emoji: EmojiValue | string): Promise<void>;
     /** Delete this message */
@@ -1510,14 +1662,14 @@ type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChu
 /**
  * Duck-typed stream event compatible with AI SDK's `fullStream`.
  * - `text-delta` events are extracted as text output.
- * - `step-finish` events trigger paragraph separators between steps.
+ * - `finish-step` events trigger paragraph separators between steps.
  * - All other event types (tool-call, tool-result, etc.) are silently skipped.
  */
 type StreamEvent = {
     textDelta: string;
     type: "text-delta";
 } | {
-    type: "step-finish";
+    type: "finish-step";
 } | {
     type: string;
 };
@@ -1562,6 +1714,12 @@ interface Attachment {
      * this method handles the auth automatically.
      */
     fetchData?: () => Promise<Buffer>;
+    /**
+     * Platform-specific metadata needed to reconstruct fetchData after serialization.
+     * Adapters store IDs here (e.g. WhatsApp mediaId, Telegram fileId) so that
+     * fetchData can be rebuilt when a message is rehydrated from the queue.
+     */
+    fetchMetadata?: Record<string, string>;
     /** Image/video height (if applicable) */
     height?: number;
     /** MIME type */
@@ -1857,6 +2015,27 @@ interface ActionEvent<TRawMessage = unknown> {
  * ```
  */
 type ActionHandler = (event: ActionEvent) => void | Promise<void>;
+/**
+ * Event emitted when an adapter needs dynamic options for an external select.
+ */
+interface OptionsLoadEvent {
+    /** The action ID of the select requesting options */
+    actionId: string;
+    /** The adapter that received this event */
+    adapter: Adapter;
+    /** The current user-entered query text */
+    query: string;
+    /** Raw platform-specific payload */
+    raw: unknown;
+    /** The user requesting options */
+    user: Author;
+}
+interface OptionsLoadGroup {
+    label: string;
+    options: SelectOptionElement[];
+}
+type OptionsLoadResult = SelectOptionElement[] | OptionsLoadGroup[];
+type OptionsLoadHandler = (event: OptionsLoadEvent) => OptionsLoadResult | Promise<OptionsLoadResult | undefined> | undefined;
 /**
  * Event emitted when a user submits a modal form.
  */
@@ -1946,7 +2125,10 @@ interface ModalPushResponse {
 interface ModalCloseResponse {
     action: "close";
 }
-type ModalResponse = ModalCloseResponse | ModalErrorsResponse | ModalUpdateResponse | ModalPushResponse;
+interface ModalClearResponse {
+    action: "clear";
+}
+type ModalResponse = ModalCloseResponse | ModalClearResponse | ModalErrorsResponse | ModalUpdateResponse | ModalPushResponse;
 type ModalSubmitHandler = (event: ModalSubmitEvent) => void | Promise<ModalResponse | void | undefined>;
 type ModalCloseHandler = (event: ModalCloseEvent) => void | Promise<void>;
 /**
@@ -2073,6 +2255,141 @@ interface MemberJoinedChannelEvent {
     userId: string;
 }
 type MemberJoinedChannelHandler = (event: MemberJoinedChannelEvent) => void | Promise<void>;
+/**
+ * Resolves a stable, cross-platform user key from an inbound message context.
+ *
+ * Return `null` to skip persistence for this event (unknown user, system
+ * message, or the bot itself). The SDK fails loudly rather than silently
+ * falling back to a platform-specific ID.
+ */
+type IdentityResolver = (context: IdentityContext) => string | null | Promise<string | null>;
+interface IdentityContext {
+    /** Adapter name (e.g. "slack", "discord"). */
+    adapter: string;
+    author: Author;
+    message: Message;
+}
+/**
+ * Role tag on a stored message.
+ *
+ * - `user`: produced by the resolved end-user
+ * - `assistant`: produced by this bot
+ * - `system`: SDK-injected marker (handoff, summary). Adapters never produce it.
+ */
+type TranscriptRole = "user" | "assistant" | "system";
+interface TranscriptEntry {
+    /** mdast AST. Only present when `transcripts.storeFormatted` is true. */
+    formatted?: FormattedContent;
+    /**
+     * UUID assigned by the SDK at append time. Opaque — not lexicographically
+     * sortable. Entries are returned by `list()` in append order (the underlying
+     * list semantics of `state.appendToList`); use `timestamp` to reason about
+     * ordering across stores.
+     */
+    id: string;
+    /** Originating adapter name. */
+    platform: string;
+    /** Platform-native message ID, when known. */
+    platformMessageId?: string;
+    role: TranscriptRole;
+    /** Plain-text body — canonical field for prompt building. */
+    text: string;
+    /** Originating thread ID. */
+    threadId: string;
+    /** ms-since-epoch, set at append time on the SDK side. */
+    timestamp: number;
+    /** Cross-platform user key from the IdentityResolver. */
+    userKey: string;
+}
+/** Duration shorthand: e.g. `"7d"`, `"30m"`, `"2h"`, `"45s"`. */
+type DurationString = `${number}${"s" | "m" | "h" | "d"}`;
+interface TranscriptsConfig {
+    /** Hard cap; older messages evicted on append. Default 200. */
+    maxPerUser?: number;
+    /**
+     * Default retention applied as the list TTL. Refreshed on every append
+     * (matches `appendToList` semantics). Omit for no expiry.
+     */
+    retention?: number | DurationString;
+    /** Persist `formatted` (mdast). Default false to keep storage small. */
+    storeFormatted?: boolean;
+}
+/**
+ * Input shape for appending a non-Message (e.g. an assistant reply you
+ * just posted via `thread.post()`).
+ */
+interface AppendInput {
+    formatted?: FormattedContent;
+    platformMessageId?: string;
+    role: TranscriptRole;
+    text: string;
+}
+interface AppendOptions {
+    /**
+     * Required when appending an `AppendInput` (assistant/system role) — the
+     * SDK has no Message instance from which to read the resolved key.
+     *
+     * Ignored when appending a Message; the Message's own `userKey` is used.
+     */
+    userKey?: string;
+}
+interface ListQuery {
+    /** Newest N kept (still returned in chronological order). Default 50. */
+    limit?: number;
+    /** Filter to a subset of adapter names. */
+    platforms?: string[];
+    /** Filter to specific roles. Default: all. */
+    roles?: TranscriptRole[];
+    /** Filter to a single thread. */
+    threadId?: string;
+    userKey: string;
+}
+/**
+ * Target for {@link TranscriptsApi.delete}. Wipes every stored message under
+ * the given user key.
+ */
+interface DeleteTarget {
+    userKey: string;
+}
+/** Query shape for {@link TranscriptsApi.count}. */
+interface CountQuery {
+    userKey: string;
+}
+/**
+ * Cross-platform per-user message store.
+ *
+ * Distinct from the existing per-thread `threadHistory` config (which exists
+ * to backfill thread context for adapters that lack server-side history APIs).
+ * The Transcripts API is keyed by a resolved cross-platform user key and is
+ * intended for transcript-style use cases (LLM context building, audit).
+ */
+interface TranscriptsApi {
+    /**
+     * Persist a Message (or AppendInput) under the user key.
+     *
+     * - For Message: `userKey` is read from the Message instance (set by the
+     *   SDK during inbound dispatch via the configured IdentityResolver).
+     *   No-op if the Message has no `userKey` (resolver returned null).
+     * - For AppendInput: `options.userKey` is required.
+     */
+    append<TState = Record<string, unknown>, TRawMessage = unknown>(thread: Postable<TState, TRawMessage>, message: Message | AppendInput, options?: AppendOptions): Promise<TranscriptEntry | null>;
+    /** Total stored count for a user key. */
+    count(query: CountQuery): Promise<number>;
+    /** GDPR / DSR delete — wipes every stored message under the user key. */
+    delete(target: DeleteTarget): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Returns the most recent entries in chronological order (oldest first),
+     * capped at `query.limit` (default 50).
+     *
+     * Pagination is intentionally not supported — the store keeps at most
+     * `transcripts.maxPerUser` entries per user. To widen the window, raise
+     * `maxPerUser`; to fetch a different slice, narrow with `threadId` /
+     * `platforms` / `roles`.
+     */
+    list(query: ListQuery): Promise<TranscriptEntry[]>;
+}
 
 /**
  * Message class with serialization support for workflow engines.
@@ -2118,6 +2435,7 @@ interface SerializedMessage {
         size?: number;
         width?: number;
         height?: number;
+        fetchMetadata?: Record<string, string>;
     }>;
     author: {
         userId: string;
@@ -2204,8 +2522,20 @@ declare class Message<TRawMessage = unknown> {
      * ```
      */
     isMention?: boolean;
+    /**
+     * Cross-platform user key for this message's author.
+     *
+     * Set by the Chat SDK before passing the message to handlers, when
+     * `ChatConfig.identity` is configured. `undefined` if no resolver is
+     * configured; `undefined` (i.e. absent) when the resolver returned null.
+     *
+     * Used by the Transcripts API to look up / append per-user transcripts.
+     */
+    userKey?: string;
     /** Links found in the message */
     links: LinkPreview[];
+    private _subjectPromise?;
+    get subject(): Promise<MessageSubject | null>;
     constructor(data: MessageData<TRawMessage>);
     /**
      * Serialize the message to a plain JSON object.
@@ -2369,6 +2699,14 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * ```
      */
     registerSingleton(): this;
+    /**
+     * Cross-platform per-user transcript store.
+     *
+     * Available only when `transcripts` is configured on the Chat instance
+     * (and an `identity` resolver is set). Throws on access otherwise so
+     * callers fail loudly rather than silently no-op'ing.
+     */
+    get transcripts(): TranscriptsApi;
     /**
      * Get the registered singleton Chat instance.
      * Throws if no singleton has been registered.
@@ -2386,9 +2724,12 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
     private readonly _fallbackStreamingPlaceholderText;
     private readonly _dedupeTtlMs;
     private readonly _onLockConflict;
-    private readonly _messageHistory;
+    private readonly _threadHistory;
+    private readonly _identity;
+    private readonly _transcripts;
     private readonly _concurrencyStrategy;
     private readonly _concurrencyConfig;
+    private readonly _concurrentSlots;
     private readonly _lockScope;
     private readonly mentionHandlers;
     private readonly directMessageHandlers;
@@ -2396,6 +2737,7 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
     private readonly subscribedMessageHandlers;
     private readonly reactionHandlers;
     private readonly actionHandlers;
+    private readonly optionsLoadHandlers;
     private readonly modalSubmitHandlers;
     private readonly modalCloseHandlers;
     private readonly slashCommandHandlers;
@@ -2571,6 +2913,12 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      */
     onAction(handler: ActionHandler): void;
     onAction(actionIds: string[] | string, handler: ActionHandler): void;
+    /**
+     * Register a handler for loading dynamic options for external selects.
+     * Specific action IDs run before catch-all handlers.
+     */
+    onOptionsLoad(handler: OptionsLoadHandler): void;
+    onOptionsLoad(actionIds: string[] | string, handler: OptionsLoadHandler): void;
     /**
      * Register a handler for modal form submissions.
      *
@@ -2686,7 +3034,7 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * Handles waitUntil registration and error catching internally.
      * Adapters should call this instead of handleIncomingMessage directly.
      */
-    processMessage(adapter: Adapter, threadId: string, messageOrFactory: Message | (() => Promise<Message>), options?: WebhookOptions): void;
+    processMessage(adapter: Adapter, threadId: string, messageOrFactory: Message | (() => Promise<Message>), options?: WebhookOptions): Promise<void>;
     /**
      * Process an incoming reaction event from an adapter.
      * Handles waitUntil registration and error catching internally.
@@ -2701,7 +3049,8 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
     processAction(event: Omit<ActionEvent, "thread" | "openModal"> & {
         adapter: Adapter;
     }, options: WebhookOptions | undefined): Promise<void>;
-    processModalSubmit(event: Omit<ModalSubmitEvent, "relatedThread" | "relatedMessage" | "relatedChannel">, contextId?: string, _options?: WebhookOptions): Promise<ModalResponse | undefined>;
+    processOptionsLoad(event: OptionsLoadEvent, _options?: WebhookOptions): Promise<OptionsLoadResult | undefined>;
+    processModalSubmit(event: Omit<ModalSubmitEvent, "relatedThread" | "relatedMessage" | "relatedChannel">, contextId?: string, options?: WebhookOptions): Promise<ModalResponse | undefined>;
     processModalClose(event: Omit<ModalCloseEvent, "relatedThread" | "relatedMessage" | "relatedChannel">, contextId?: string, options?: WebhookOptions): void;
     /**
      * Process an incoming slash command from an adapter.
@@ -2768,6 +3117,23 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * ```
      */
     openDM(user: string | Author): Promise<Thread<TState>>;
+    /**
+     * Look up user information by user ID.
+     *
+     * The adapter is automatically inferred from the user ID format.
+     * Returns user details including email (where available — requires
+     * appropriate scopes on some platforms, e.g. `users:read.email` on Slack).
+     *
+     * @param user - Platform-specific user ID string, or an Author object
+     * @returns User info, or null if user not found
+     *
+     * @example
+     * ```typescript
+     * const user = await chat.getUser("U123456");
+     * console.log(user?.email); // "alice@company.com"
+     * ```
+     */
+    getUser(user: string | Author): Promise<UserInfo | null>;
     /**
      * Get a Channel by its channel ID.
      *
@@ -2795,6 +3161,21 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * ```
      */
     channel(channelId: string): Channel<TState>;
+    /**
+     * Get a Thread handle by its thread ID.
+     *
+     * The adapter is automatically inferred from the thread ID prefix.
+     *
+     * @param threadId - Full thread ID (e.g., "slack:C123ABC:1234567890.123456")
+     * @returns A Thread that can be used to post messages, subscribe, etc.
+     *
+     * @example
+     * ```typescript
+     * const thread = chat.thread("slack:C123ABC:1234567890.123456");
+     * await thread.post("Hello from outside a webhook!");
+     * ```
+     */
+    thread(threadId: string): Thread<TState>;
     /**
      * Infer which adapter to use based on the userId format.
      */
@@ -2835,9 +3216,12 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      */
     private drainQueue;
     /**
-     * Concurrent strategy: no locking, process immediately.
+     * Concurrent strategy: no locking, process immediately — but cap
+     * simultaneous handlers per thread at `maxConcurrent` (default Infinity).
      */
     private handleConcurrent;
+    private acquireConcurrentSlot;
+    private releaseConcurrentSlot;
     /**
      * Dispatch a message to the appropriate handler chain based on
      * subscription status, mention detection, and pattern matching.
@@ -2881,6 +3265,21 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
  */
 declare function fromFullStream(stream: AsyncIterable<unknown>): AsyncIterable<string | StreamChunk>;
 
+/**
+ * @deprecated Renamed — import from `./thread-history` instead.
+ *
+ * This module is preserved for backwards compatibility and re-exports the
+ * new names under the old identifiers. New code should use `ThreadHistoryCache`
+ * and `ThreadHistoryConfig` directly.
+ */
+
+/** @deprecated Use `ThreadHistoryConfig` from `./thread-history` instead. */
+type MessageHistoryConfig = ThreadHistoryConfig;
+/** @deprecated Use `ThreadHistoryCache` from `./thread-history` instead. */
+declare const MessageHistoryCache: typeof ThreadHistoryCache;
+/** @deprecated Use `ThreadHistoryCache` from `./thread-history` instead. */
+type MessageHistoryCache = ThreadHistoryCache;
+
 /**
  * Standalone JSON reviver for Chat SDK objects.
  *
@@ -2953,6 +3352,58 @@ declare class StreamingMarkdownRenderer {
     private formatAppendOnlyText;
 }
 
+interface StreamingPlanOptions {
+    /**
+     * Block Kit elements to attach when the stream stops (Slack only).
+     * Useful for adding feedback buttons after a streamed response.
+     */
+    endWith?: unknown[];
+    /**
+     * Controls how task_update chunks are displayed (Slack only).
+     * - `"plan"` - all tasks grouped into a single plan block
+     * - `"timeline"` - individual task cards shown inline with text (default)
+     */
+    groupTasks?: "plan" | "timeline";
+    /**
+     * Minimum interval between updates in ms (default: 500).
+     * Used by post+edit streaming paths.
+     */
+    updateIntervalMs?: number;
+}
+interface StreamingPlanData {
+    options: StreamingPlanOptions;
+    stream: AsyncIterable<string | StreamChunk | StreamEvent>;
+}
+/**
+ * A StreamingPlan wraps an async iterable with platform-specific streaming options.
+ *
+ * Use this when you need to pass options like task grouping or stop blocks
+ * to the streaming API. For simple streaming without options, pass the
+ * async iterable directly to `thread.post()`.
+ *
+ * @example
+ * ```typescript
+ * const stream = new StreamingPlan(result.fullStream, {
+ *   groupTasks: "plan",
+ *   endWith: [feedbackBlock],
+ * });
+ * await thread.post(stream);
+ * ```
+ */
+declare class StreamingPlan implements PostableObject<StreamingPlanData> {
+    readonly $$typeof: symbol;
+    readonly kind = "stream";
+    private readonly _stream;
+    private readonly _options;
+    constructor(stream: AsyncIterable<string | StreamChunk | StreamEvent>, options?: StreamingPlanOptions);
+    get stream(): AsyncIterable<string | StreamChunk | StreamEvent>;
+    get options(): StreamingPlanOptions;
+    getFallbackText(): string;
+    getPostData(): StreamingPlanData;
+    isSupported(_adapter: Adapter): boolean;
+    onPosted(_context: PostableObjectContext): void;
+}
+
 /**
  * Get or create an immutable singleton EmojiValue.
  *
@@ -3037,7 +3488,7 @@ declare const defaultEmojiResolver: EmojiResolver;
  * // Returns: "Thanks! 👍"
  * ```
  */
-declare function convertEmojiPlaceholders(text: string, platform: "slack" | "gchat" | "teams" | "discord" | "github" | "linear" | "whatsapp", resolver?: EmojiResolver): string;
+declare function convertEmojiPlaceholders(text: string, platform: "slack" | "gchat" | "teams" | "discord" | "messenger" | "github" | "linear" | "whatsapp", resolver?: EmojiResolver): string;
 /** Base emoji object with well-known emoji as EmojiValue singletons */
 type BaseEmojiHelper = {
     [K in WellKnownEmoji]: EmojiValue;
@@ -3390,10 +3841,11 @@ declare const toModalElement: typeof toModalElement$1;
 
 declare const fromReactModalElement: typeof fromReactModalElement$1;
 declare const isModalElement: typeof isModalElement$1;
+declare const ExternalSelect: ExternalSelectComponent;
 declare const Modal: ModalComponent;
 declare const RadioSelect: RadioSelectComponent;
 declare const Select: SelectComponent;
 declare const SelectOption: SelectOptionComponent;
 declare const TextInput: TextInputComponent;
 
-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, reviver, 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 AppendInput, type AppendOptions, 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 CountQuery, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DeleteTarget, type DirectMessageHandler, Divider, DividerComponent, type DurationString, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, ExternalSelect, ExternalSelectComponent, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, type IdentityContext, type IdentityResolver, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListQuery, 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, type MessageSubject, Modal, type ModalClearResponse, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, type OptionsLoadEvent, type OptionsLoadGroup, type OptionsLoadHandler, type OptionsLoadResult, 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, SelectOptionElement, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StartPlanOptions, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, StreamingPlan, type StreamingPlanData, type StreamingPlanOptions, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadHistoryCache, type ThreadHistoryConfig, ThreadImpl, type ThreadInfo, type ThreadSummary, type TranscriptEntry, type TranscriptRole, type TranscriptsApi, type TranscriptsConfig, type UpdateTaskInput, type UserInfo, 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, reviver, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };