@cursor/bdk 0.2.1

package/src/channels/slack/types.ts

@@ -0,0 +1,782 @@
+/**
+ * Types for the Slack platform channel pack.
+ */
+
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
+import type {
+  AgentCloudOptions,
+  ArtifactsApi,
+  AuthContext,
+  ChannelEventHandlers,
+  HostContext,
+} from "../../types.js";
+import type { SlackReplyFooter } from "./footer.js";
+
+export type { SlackReplyFooter, SlackReplyFooterContext } from "./footer.js";
+
+/**
+ * Pluggable Slack Web API caller. Instead of holding a raw `xoxb-…` token,
+ * calls are executed by `call`. Implementations return the Slack response
+ * body (including `ok: false` platform errors) and only throw on
+ * programmer error.
+ */
+export interface SlackApiTransport {
+  kind: "api-transport";
+  /** Human-readable transport label for logs. */
+  label: string;
+  call(method: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+/** Bot token as a string, a (possibly async) resolver, or an API transport. */
+export type SlackBotToken = string | (() => string | Promise<string>) | SlackApiTransport;
+
+export interface SlackCredentials {
+  /**
+   * Bot user OAuth token (`xoxb-…`), or a {@link SlackApiTransport} that
+   * executes Web API calls without a local token. When omitted, falls back
+   * to `SLACK_BOT_TOKEN` (or `{envPrefix}_SLACK_BOT_TOKEN` via
+   * {@link SlackChannelOptions.envPrefix}).
+   */
+  botToken?: SlackBotToken;
+  /**
+   * App-level token (`xapp-…`) for Socket Mode. Requires scope
+   * `connections:write`. Same fallback rules as `botToken`.
+   */
+  appToken?: string | (() => string | Promise<string>);
+}
+
+/** Per-session Slack adapter state. */
+export interface SlackChannelState {
+  channelId: string | null;
+  threadTs: string | null;
+  teamId: string | null;
+  triggeringUserId: string | null;
+  pendingToolCallMessage: string | null;
+  lastReasoningTypingAtMs: number | null;
+  lastReasoningTypingStatus: string | null;
+  /** Active chat stream message ts (`chat.startStream`). */
+  streamTs: string | null;
+  /** Channel id used when the stream was started. */
+  streamChannelId?: string | null;
+  /** Last assistant text delivered to the thread (stream or postMessage). */
+  lastPostedText?: string | null;
+  /**
+   * Text of the current assistant block already written into the open stream.
+   * The harness restarts its cumulative text at every tool boundary, so the
+   * append delta cannot be measured against {@link lastPostedText}.
+   */
+  streamBlockText?: string | null;
+  /**
+   * Slack message ts of the agent's last delivered reply in this thread.
+   * Warm turns use this as the `<slack_thread_delta>` watermark.
+   */
+  lastBotMessageTs?: string | null;
+  /** Admission already posted the static placeholder; execution must not post it again. */
+  placeholderPosted?: boolean;
+  /**
+   * When true, stream APIs failed for this session — use postMessage
+   * for the rest of the turn.
+   */
+  streamingUnavailable?: boolean;
+  /** The open stream hit Slack's size cap; appends stop until it closes. */
+  streamFull?: boolean;
+  /** Chunks Slack accepted on the open stream, reported when it closes. */
+  streamAppendedChunks?: number;
+  /** Editable progress message ts when `chat.startStream` is unavailable. */
+  progressTs: string | null;
+  /**
+   * Message ts of approval cards keyed by tool call id (for
+   * replacing Approve/Deny buttons after a decision).
+   */
+  approvalMessageByCallId?: Record<string, string>;
+  /** `reply.reasoningCard` bookkeeping for the current turn. */
+  reasoningCard?: ReasoningCardState;
+  /** `reply.toolCards` per-tool tallies for the current turn, keyed by tool name. */
+  toolCardCounts?: Record<string, ToolCardCount>;
+  /** Staged `post-file` uploads this turn (`agentic`). */
+  agenticFiles?: Array<{ path: string; name: string; workspace: string }>;
+  /** Inbound already started ack + chip; `turn.started` skips the backstop. */
+  startPainted?: boolean;
+  /** `Date.now()` at `turn.started`. Footer elapsed time is measured from this. */
+  turnStartedAtMs?: number | null;
+}
+
+/**
+ * Slack appends a task card's `details` across updates, so the reasoning
+ * card is fed deltas: `blockSent` is how much of the current reasoning block
+ * is already on Slack, `pending` is buffered text awaiting a flush.
+ */
+export interface ReasoningCardState {
+  status: "in_progress" | "complete" | null;
+  blockSent: number | null;
+  pending: string;
+  lastFlushMs: number | null;
+  chars: number;
+}
+
+/**
+ * `details` / `output` count the lines already on the card, so a later
+ * batch can start on a new line (Slack appends updates verbatim).
+ */
+export interface ToolCardCount {
+  started: number;
+  done: number;
+  errors: number;
+  details?: number;
+  output?: number;
+}
+
+/** A tool call as the model requested it (`actions.requested`). */
+export interface SlackToolCall {
+  callId: string;
+  toolName: string;
+  args?: unknown;
+}
+
+/** A finished tool call (`action.result`). */
+export interface SlackToolResult {
+  callId: string;
+  toolName: string;
+  output?: unknown;
+  isError: boolean;
+}
+
+/**
+ * What the status chip under the thread shows while a turn runs. Slack caps
+ * each line at 50 characters. While a `chat.startStream` is open Slack shows
+ * its own generic "is working…" instead, so in `"stream"` mode these lines
+ * are only visible until the first chunk goes out.
+ */
+export interface SlackStatusOptions {
+  /** First line of each reasoning block, throttled. Defaults to `true`. */
+  reasoning?: boolean;
+  /**
+   * Tool calls as they start: `"Running grep, glob…"` (tool names through
+   * {@link SlackChannelOptions.toolLabels}), or your own line. Defaults to
+   * `true`.
+   */
+  tools?: boolean | ((calls: readonly SlackToolCall[]) => string);
+  /**
+   * Rotation Slack cycles through while nothing more specific is known
+   * (turn start, long silent stretches). Up to 5 entries. Defaults to
+   * Thinking… / Working on it… / Almost there….
+   */
+  idle?: readonly string[];
+}
+
+export type SlackToolCardGroup = "per-call" | "per-tool";
+
+/**
+ * Task cards for tool calls inside the streamed reply. Slack appends each
+ * update's `details` / `output` to the card, so the callbacks return the
+ * text to add, not the full card.
+ */
+export interface SlackToolCardOptions {
+  /**
+   * `"per-tool"` (default) keeps one card per tool name and counts calls in
+   * the title (`grep ×3`). `"per-call"` shows one card per call.
+   */
+  group?: SlackToolCardGroup;
+  /**
+   * `true` (default): cards expand to show one line per call, the way the
+   * reasoning card does. `false`: cards are their titles only.
+   */
+  collapsible?: boolean;
+  /**
+   * The line a collapsible card shows for a call. Defaults to what the
+   * playground shows in that tool's header: the grep pattern, the file
+   * path, the shell command.
+   */
+  details?: (call: SlackToolCall) => string | undefined;
+  /** Text appended to a collapsible card when a call finishes. */
+  output?: (result: SlackToolResult) => string | undefined;
+}
+
+/**
+ * One task card that receives the model's reasoning as it streams. Its
+ * status is `in_progress` while the model thinks and `complete` once the
+ * answer text starts.
+ */
+export interface SlackReasoningCardOptions {
+  /** Card title. Defaults to `"Thinking"`. */
+  title?: string;
+  /**
+   * Stop appending after this many characters. Defaults to 1500: Slack caps
+   * a streamed message (answer text plus cards) near 12k, so a long card
+   * shortens the answer that fits before the reply spills into a second
+   * message.
+   */
+  maxChars?: number;
+}
+
+/**
+ * How the reply reaches the thread while the turn runs.
+ *
+ * - `"post"` (default): live feedback is the status chip; the answer lands
+ *   as one message when the turn finishes.
+ * - `"stream"`: the answer text streams into one message as it is written.
+ *   Slack replaces the status chip with its generic "is working…" for the
+ *   duration, so live feedback inside the message comes from cards.
+ * - `"agentic"`: inbound still starts turns. At turn start the channel
+ *   acks the parent and raises the thinking chip, then paints thinking
+ *   from `reasoning.appended` and tool lines from `actions.requested`
+ *   (last assistant line before a `tool_call` wins when present).
+ *   Model `set-status` does not own the chip. It does not write tool
+ *   cards, reasoning cards, or assistant text. It watches `post-update`,
+ *   `post-file`, `post-card`, `react`, `edit-message`, and
+ *   `delete-message` and renders those.
+ */
+export type SlackReplyOptions =
+  | {
+      mode: "post";
+      status?: SlackStatusOptions;
+      footer?: SlackReplyFooter;
+    }
+  | {
+      mode: "stream";
+      status?: SlackStatusOptions;
+      /** Defaults to `false`. `true` is `{ group: "per-tool" }`. */
+      toolCards?: boolean | SlackToolCardOptions;
+      /** Defaults to `false`. */
+      reasoningCard?: boolean | SlackReasoningCardOptions;
+      footer?: SlackReplyFooter;
+    }
+  | {
+      mode: "agentic";
+      /**
+       * Reaction on the parent at turn start. Slack name, with or without
+       * colons. Default `eyes`.
+       */
+      ack?: string;
+      /**
+       * Post this exact static line as the first message (`chat.startStream`
+       * when Slack allows, then `stopStream` so the chip can paint). The
+       * first `post-update` edits that same ts. Maximum 80 characters.
+       */
+      placeholder?: string;
+      /** Chip while the turn runs. Reasoning and tools default on. Idle is ignored. */
+      status?: Omit<SlackStatusOptions, "idle">;
+      footer?: SlackReplyFooter;
+    };
+
+/**
+ * Human labels for tool names, shared by the status chip and the cards.
+ * A function may return `undefined` to keep the raw tool name.
+ */
+export type SlackToolLabels =
+  | Readonly<Record<string, string>>
+  | ((toolName: string) => string | undefined);
+
+export interface SlackAuthor {
+  /** Slack user id. Empty string for bot posts with no `user` field. */
+  userId: string;
+  userName?: string;
+  isBot: boolean;
+  /** Posting app's `bot_id` (`B…`) when the message is bot-authored. */
+  botId?: string;
+}
+
+export interface SlackReactionAddedInfo {
+  /** Slack reaction name without surrounding colons. */
+  name: string;
+  /** User id of the message author, when Slack includes it. */
+  itemUserId?: string;
+}
+
+/**
+ * Delegation metadata carried on bot-to-bot mention posts (Slack message
+ * `metadata`, event type {@link SLACK_DELEGATION_METADATA_EVENT_TYPE}).
+ * Absent on posts from bots that don't speak the protocol — the gate then
+ * treats the mention as depth 1.
+ */
+export interface SlackDelegationInfo {
+  /** Delegation hop count. A dispatcher woken by a human posts depth 1. */
+  depth: number;
+  /** Mount slug / display name of the delegating agent. */
+  fromAgent?: string;
+  /** Session id on the delegating agent, for cross-agent tracing. */
+  originSessionId?: string;
+}
+
+/** File upload on an inbound Slack message (see {@link SlackMessage.files}). */
+export interface SlackMessageFile {
+  id: string;
+  name?: string;
+  title?: string;
+  mimetype?: string;
+  filetype?: string;
+  mode?: string;
+  size?: number;
+  /**
+   * When set, bytes were already downloaded by the caller. Skip a second
+   * `files.info` / private URL fetch.
+   */
+  dataBase64?: string;
+}
+
+export interface SlackMessage {
+  /** Raw top-level `text` exactly as Slack sent it. Often empty on bot posts. */
+  text: string;
+  /**
+   * Raw mrkdwn body: top-level `text` plus attachment / Block Kit content.
+   * Alert feeds (Datadog, PagerDuty) leave `text` empty and put the whole
+   * notification in attachments, so read `body` for message content. Unlike
+   * {@link markdown} this keeps `<url|label>` links intact.
+   */
+  body: string;
+  /** Body roughly suitable for the model (mention markers cleaned). */
+  markdown: string;
+  ts: string;
+  threadTs: string;
+  channelId: string;
+  teamId?: string;
+  author?: SlackAuthor;
+  /** Present only for a synthetic message dispatched from `reaction_added`. */
+  reaction?: SlackReactionAddedInfo;
+  /** Parsed delegation metadata when the post carried it (bot mentions). */
+  delegation?: SlackDelegationInfo;
+  /**
+   * Slack file uploads on this message (top-level + forwarded shares).
+   * Downloaded during dispatch into vision images / workspace files.
+   */
+  files?: SlackMessageFile[];
+}
+
+export interface SlackDispatchDecision {
+  auth: AuthContext | null;
+  /** Extra context blocks injected alongside the default Slack context. */
+  context?: string[];
+  /**
+   * Override the user prompt sent to the model. When omitted, uses the Slack
+   * message markdown (plus context blocks). Host-prepared reviews can pass
+   * a short "read pr.txt" prompt here.
+   */
+  message?: string;
+  /**
+   * Absolute directory used as the local harness `cwd` for this session
+   * (new sessions only).
+   */
+  workspaceDir?: string;
+  /**
+   * Relative path → contents written into the session workspace before the
+   * first turn (new sessions only). Prefer this for host-prepared files like
+   * `pr.txt` so default skill materialization stays on the session cwd.
+   * Values may be utf8 strings or `{ encoding: "base64", data }` blobs.
+   */
+  workspaceFiles?: Record<string, string | { encoding: "base64"; data: string; mimeType?: string }>;
+  /**
+   * Base64 images attached to this turn for vision (Cursor SDK `images`).
+   * Populated automatically from Slack file uploads during inbound dispatch.
+   */
+  images?: Array<{ data: string; mimeType: string }>;
+  /** Session display title (new sessions only). */
+  title?: string;
+  /**
+   * Per-session cloud options (new sessions only). Use this to attach a PR to
+   * a cloud agent from an inbound Slack mention.
+   */
+  cloud?: AgentCloudOptions;
+  /**
+   * Seed the Cursor SDK agent id for a new session (ignored when the thread
+   * already has one). Lets a handler reattach a Slack thread to an existing
+   * cloud conversation (e.g. per-PR `bc-…` affinity).
+   */
+  sdkAgentId?: string;
+  /**
+   * Additional Slack message timestamps to omit from `<slack_thread>` hydration
+   * (e.g. every message in a coalesced batch already folded into `message`).
+   */
+  excludeThreadTimestamps?: readonly string[];
+}
+
+export interface SlackSuggestedPrompt {
+  title: string;
+  message: string;
+}
+
+export interface SlackThreadHandle {
+  post(text: string, options?: { blocks?: unknown[] }): Promise<{ ts: string }>;
+  startTyping(status: string, loadingMessages?: string[]): Promise<void>;
+  setTitle(title: string): Promise<void>;
+  setSuggestedPrompts(prompts: SlackSuggestedPrompt[], title?: string): Promise<void>;
+}
+
+export interface SlackBinding {
+  thread: SlackThreadHandle;
+  slack: {
+    channelId: string;
+    threadTs: string;
+    teamId?: string;
+  };
+  /** Shared host services (MCP / GitHub / Slack). */
+  host: HostContext;
+  /**
+   * Durable artifacts (unbound — the handler runs before any session is
+   * admitted; pass `sessionId` in `tag` input to attribute one).
+   */
+  artifacts: ArtifactsApi;
+}
+
+export type SlackMessageHandler = (
+  ctx: SlackBinding,
+  message: SlackMessage,
+) => SlackDispatchDecision | null | undefined | Promise<SlackDispatchDecision | null | undefined>;
+
+/**
+ * Host probes into a Slack thread's continuation. Optional on dispatch
+ * deps; the serve host wires them at channel start.
+ */
+export interface SlackContinuationProbes {
+  /**
+   * When set, full-thread hydration runs only for cold-start turns (no
+   * existing session). Warm turns load a `<slack_thread_delta>` instead.
+   */
+  hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
+  /** True when a turn is already running for this Slack continuation. */
+  isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
+  /**
+   * Warm-delta watermark from session channel state (`lastBotMessageTs`).
+   * When absent, delta falls back to the last matching bot post in-thread.
+   */
+  getContinuationLastBotMessageTs?: (continuationToken: string) => Promise<string | undefined>;
+  /** Cancel the active turn + clear coalesced nudges for this continuation. */
+  interruptContinuation?: (continuationToken: string) => Promise<boolean>;
+}
+
+/**
+ * A Block Kit action click (Socket Mode `block_actions` payload) that the
+ * framework does not own — the built-in tool-approval Approve/Deny actions
+ * are routed to `resolveApproval` before author handlers see anything.
+ */
+export interface SlackBlockAction {
+  /** `action_id` of the clicked element. */
+  actionId: string;
+  /** `block_id` of the actions row holding the element (Slack always sets one). */
+  blockId: string;
+  /**
+   * Element `value` payload; empty string when absent (button-style
+   * elements only — select/overflow `selected_option`s are not read).
+   */
+  value: string;
+  /** Plain-text label of the clicked element, when present. */
+  label?: string;
+  channelId: string;
+  /**
+   * Thread of the message carrying the element (the message's own ts when
+   * it is a top-level post — clicks on a thread root stay in its thread).
+   */
+  threadTs: string;
+  /** The message carrying the clicked element. */
+  messageTs: string;
+  /** That message's blocks, for `chat.update` resolution cards. */
+  messageBlocks?: unknown[];
+  /** Slack user who clicked. */
+  userId: string;
+  userName?: string;
+  teamId?: string;
+  /**
+   * Slack `action_ts` — unique per click; block-action dispatch dedupes on
+   * it. Empty when the payload omitted it (malformed; never dispatched).
+   */
+  actionTs: string;
+}
+
+/**
+ * Author handler for {@link SlackBlockAction} clicks. Return a
+ * {@link SlackDispatchDecision} to dispatch a turn on the click's thread —
+ * the click is dispatched like an inbound message from the clicking user
+ * (thread-scoped continuation, `<slack_context>` naming the clicker) — or
+ * `null` to ignore the click.
+ */
+export type SlackBlockActionHandler = (
+  ctx: SlackBinding,
+  action: SlackBlockAction,
+) => SlackDispatchDecision | null | undefined | Promise<SlackDispatchDecision | null | undefined>;
+
+/**
+ * Opt-in channel watch: dispatch on posts in configured channels without an
+ * @mention. Mentions stay global (any channel the bot is in). Listening
+ * without a mention names its channels, or `"*"` for every channel the bot
+ * is in — thread replies only.
+ */
+export interface SlackChannelPostsOptions {
+  /**
+   * Channels to watch. Either a lone `"*"` (every channel the bot is in;
+   * thread replies only — set `posts: "replies"`) or a finite list: at
+   * least one channel id (`C…` / `G…`), at most 10 distinct ids. Mixing
+   * `"*"` with ids is a definition error. `#name` entries may accompany
+   * ids (resolved via `conversations.list` on Socket Mode). On
+   * Cursor-managed hosting, id entries become channel-scoped
+   * subscriptions. A lone `"*"` is the guest watcher only: it is omitted
+   * from the deploy manifest, and a thread reply is delivered when a
+   * mention already opened that thread. The bot must be a member of a
+   * channel to receive its messages.
+   */
+  allow: string[];
+  /**
+   * Which posts dispatch. `"top-level"` (default) fires only on new
+   * channel posts — never on replies inside other people's threads.
+   * `"replies"` is the opposite: thread replies only (`ts !== threadTs`),
+   * never a top-level post. `"all"` is both. A lone `"*"` allowlist
+   * requires `"replies"`.
+   */
+  posts?: "top-level" | "all" | "replies";
+  /**
+   * Delay dispatch by this many milliseconds so rapid edits settle first.
+   * Edits during the window update the dispatched text; deleting the post
+   * cancels the dispatch. Defaults to `0` (immediate). Socket Mode only —
+   * the Cursor relay does not deliver edits/deletes.
+   */
+  debounceMs?: number;
+  /**
+   * Also dispatch bot-authored posts (alert feeds, webhook integrations,
+   * other agents posting notes). Defaults to `false` — human posts only.
+   * The watching bot's own posts are always dropped regardless (loop
+   * safety), matched by the app's `bot_id` / bot user id from `auth.test`.
+   */
+  includeBotPosts?: boolean;
+}
+
+/**
+ * Opt-in bot-to-bot mention wake: allow @mentions authored by explicitly
+ * trusted bots (e.g. a dispatcher agent) to dispatch like human mentions.
+ * Default off — bot-authored mentions are dropped (loop safety). There is
+ * deliberately no "any bot" wildcard; trusting a bot is a per-bot decision.
+ *
+ * Loop protection is layered: this allowlist, the always-on own-post
+ * filter, a delegation-depth budget (Slack message metadata), and a
+ * per-thread wake budget.
+ */
+export interface SlackBotMentionsOptions {
+  /**
+   * Bots whose mentions may wake this agent. Three entry forms:
+   *
+   * - `"B…"` — a `bot_id` (dedicated Slack app).
+   * - `"U…"` — a bot *user* id.
+   * - `"<botId>:<username>"` — compound: the posting app's `bot_id` AND its
+   *   message `username` must both match (case-insensitive username). Use
+   *   this when several agents post through one app under different
+   *   usernames. Fails closed when the event carries no username.
+   *
+   * Must be non-empty (empty is a definition error).
+   */
+  allowFrom: string[];
+  /**
+   * Maximum delegation depth admitted (from the mention's delegation
+   * metadata; mentions without metadata count as depth 1). Defaults to 2 —
+   * human → dispatcher → specialist, no deeper chains.
+   */
+  maxDepth?: number;
+  /**
+   * Maximum bot-initiated wakes per thread per hour (sliding window).
+   * Defaults to 5. Rate-limits ping-pong between bots that carry no
+   * delegation metadata; termination comes from {@link maxPerThreadTotal}.
+   */
+  maxPerThreadPerHour?: number;
+  /**
+   * Lifetime cap on bot-initiated wakes per thread (resets only after the
+   * thread has been idle for 24h). Defaults to 20. This is the terminating
+   * backstop: a sliding window alone refills, so two mutually-allowlisted
+   * bots could ping-pong forever at the rate cap. Avoid mutual allowlists
+   * regardless — keep the delegation graph a DAG.
+   */
+  maxPerThreadTotal?: number;
+}
+
+/**
+ * How the agent engages over Slack. Omitted entirely = mentions + DMs,
+ * which is also the default for each flag — summoned, never proactive.
+ */
+export interface SlackEngagementOptions {
+  /** Dispatch on `app_mention`. Defaults to `true`. */
+  mentions?: boolean;
+  /** Dispatch on direct messages (`message.im`). Defaults to `true`. */
+  directMessages?: boolean;
+  /**
+   * Opt-in channel watch (see {@link SlackChannelPostsOptions}). Requires
+   * the Slack app to subscribe to `message.channels` / `message.groups`
+   * (`slack create --channel-posts`).
+   */
+  channelPosts?: SlackChannelPostsOptions;
+  /**
+   * Opt-in bot-to-bot mention wake (see {@link SlackBotMentionsOptions}).
+   */
+  botMentions?: SlackBotMentionsOptions;
+}
+
+/** `"thread"` = anyone in the thread (default); `"author"` = session starter only. */
+export type SlackRespondTo = "thread" | "author";
+
+export interface SlackAccessPolicy {
+  /** Defaults to `"thread"`. Applied by the default inbound handlers. */
+  respondTo?: SlackRespondTo;
+  /** Refuse Slack Connect / guest / other-workspace senders. Defaults to `true`. */
+  blockExternals?: boolean;
+}
+
+export interface SlackChannelOptions {
+  credentials?: SlackCredentials;
+  /**
+   * Continuation selector. Omit this to inherit the agent architecture's
+   * default. Set it explicitly only when migrating persisted identities.
+   */
+  continuation?: ContinuationIdentity;
+  /** Defaults to `{ respondTo: "thread", blockExternals: true }`. */
+  policy?: SlackAccessPolicy;
+  /**
+   * Per-agent env prefix for tokens. `envPrefix: "MY_AGENT"` reads
+   * `MY_AGENT_SLACK_BOT_TOKEN` + `MY_AGENT_SLACK_APP_TOKEN`. Prefer this over
+   * shared `SLACK_*` vars when serving multiple agents in one process.
+   * Ignored when `credentials` is set explicitly.
+   */
+  envPrefix?: string;
+  /**
+   * Optional log sink. When omitted, uses `console.log` until the server
+   * mounts the channel and rebinds to {@link ServeOptions.logger}.
+   */
+  logger?: (line: string) => void;
+  /**
+   * Engagement surface. Defaults to mentions + DMs only; channel watch is
+   * opt-in via {@link SlackEngagementOptions.channelPosts}.
+   */
+  engagement?: SlackEngagementOptions;
+  onAppMention?: SlackMessageHandler;
+  onDirectMessage?: SlackMessageHandler;
+  /**
+   * Handler for Socket Mode `reaction_added` events on messages. The Slack
+   * app must subscribe to `reaction_added` and have `reactions:read`.
+   * The handler receives a synthetic message whose thread timestamp is the
+   * reacted-to message and whose {@link SlackMessage.reaction} names the emoji.
+   */
+  onReactionAdded?: SlackMessageHandler;
+  /**
+   * Handler for watched channel posts (same contract as `onAppMention`:
+   * return `null` to skip, or a {@link SlackDispatchDecision} to dispatch).
+   * Only consulted when `engagement.channelPosts` is configured.
+   */
+  onChannelPost?: SlackMessageHandler;
+  /**
+   * Override / extend the default stream-event handlers (typing, replies).
+   * Handlers you provide replace the matching default handlers.
+   */
+  events?: ChannelEventHandlers<SlackChannelState>;
+  /**
+   * When true (default), install the default turn sinks for `post` and
+   * `stream`, or the signal watcher for `agentic`.
+   */
+  deliverDefaults?: boolean;
+  /**
+   * How the reply reaches the thread: status chip + one message at the end
+   * (`"post"`, default), a live-streamed message with optional tool and
+   * reasoning cards (`"stream"`), or agent-owned posts (`"agentic"`).
+   * See {@link SlackReplyOptions}.
+   */
+  reply?: SlackReplyOptions;
+  /** Human labels for tool names in the status chip and cards. */
+  toolLabels?: SlackToolLabels;
+  /**
+   * @deprecated Use `reply: { mode: "stream" }` / `reply: { mode: "post" }`.
+   * Ignored when `reply` is set.
+   */
+  streaming?: boolean;
+  /**
+   * @deprecated Use `reply: { mode: "stream", toolCards: true }`. Ignored
+   * when `reply` is set.
+   */
+  thinkingSteps?: boolean;
+  /**
+   * Write Slack's assistant status chip ("Saw your follow-up…") when a
+   * follow-up coalesces into a running turn. Defaults to `true`, except
+   * when `reply.mode` is `"agentic"`.
+   *
+   * Set to `false` on channels that report progress themselves: the chip is
+   * cleared by the default `message.completed` handler, so a channel that
+   * replaces that handler has nothing to take it down and it outlives the
+   * turn.
+   */
+  followUpStatus?: boolean;
+  /**
+   * Opt in to Slack delivery for human-in-the-loop tool approvals.
+   *
+   * Framework park/resume is enabled by `needsApproval` on server tools.
+   * Set this to `true` to also post Block Kit Approve/Deny cards and route
+   * the Socket Mode `interactive` clicks to `resolveApproval`.
+   *
+   * Defaults to `false`. For custom composition, spread
+   * `buildToolApprovalEvents({ credentials })` into `events`.
+   */
+  toolApprovals?: boolean;
+  /**
+   * Route interactive payloads to approval resolution without opting into
+   * the full {@link buildToolApprovalEvents} handler pack. Use when
+   * composing `buildToolApprovalEvents` into `events` manually.
+   */
+  interactivity?: boolean;
+  /**
+   * Handler for Block Kit actions the framework does not own (the built-in
+   * tool-approval Approve/Deny clicks are routed to `resolveApproval`
+   * first). Return a {@link SlackDispatchDecision} — typically with a
+   * thread-scoped auth via `buildSlackAuthContext` so replies in the same
+   * thread continue the session — to dispatch a turn on the click's
+   * thread, or `null` to ignore the click. Setting this implies
+   * interactive routing; the Slack app manifest still needs
+   * `interactivity` enabled (`buildSlackManifest({ interactivity: true })`).
+   */
+  onBlockAction?: SlackBlockActionHandler;
+  /**
+   * Suggested prompts shown when an assistant thread starts (and optionally
+   * after a turn completes).
+   */
+  suggestedPrompts?: SlackSuggestedPrompt[];
+  suggestedPromptsTitle?: string;
+  /**
+   * @deprecated Use `reply: { mode, status: { idle: [...] } }`. Ignored when
+   * `reply` is set.
+   */
+  loadingMessages?: string[];
+  /**
+   * Built-in Slack `eval` / `eval list` / `eval status` directive that runs
+   * playground eval batches (`host.evals` / `/v1/dev/evals/runs`) without an
+   * agent turn, on mentions and DMs only. Defaults to `true`. Set `false` to
+   * leave `eval …` for the model handler instead.
+   */
+  evalCommands?: boolean;
+  /** Optional teardown (e.g. stop example-local debouncers). Runs after Socket Mode stops. */
+  onStop?: () => void | Promise<void>;
+}
+
+export interface SlackManifestOptions {
+  /** Display name for the Slack app. */
+  name: string;
+  /** Bot display name (handle without @). Defaults from `name`. */
+  botDisplayName?: string;
+  /** Env profile. Affects display name suffix. */
+  env: "dev" | "prod";
+  /** Optional short description shown in the Slack app. */
+  description?: string;
+  /** Include `agent_view` + `assistant:write` for typing status. */
+  assistant?: boolean;
+  /**
+   * Enable Slack interactivity (needed for Approve/Deny cards).
+   * Defaults to `false` — enable when using `toolApprovals: true`.
+   */
+  interactivity?: boolean;
+  /**
+   * Subscribe to `message.channels` + `message.groups` for the opt-in
+   * channel watch (`engagement.channelPosts`). Defaults to `false`.
+   */
+  channelPosts?: boolean;
+  /** Seed suggested prompts into the manifest `agent_view`. */
+  suggestedPrompts?: Array<{ title: string; message: string }>;
+  /**
+   * Emit `settings.managed_app_settings`. Defaults to `true` — Cursor
+   * provisions these apps through its manager app. Pass `false` when the
+   * caller is not a manager user token.
+   */
+  managedByCursor?: boolean;
+}
+
+/** Soft-fail result for optional Slack API features. */
+export type SoftSlackResult<T extends Record<string, unknown> = Record<string, unknown>> =
+  | ({ ok: true } & T)
+  | { ok: false; error: string; unsupported?: boolean };