@cursor/bdk 0.2.2 → 0.2.4

package/src/channels/slack/types.ts

@@ -1,787 +0,0 @@
-/**
- * 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 directory. Slack caps this at 140 characters. */
-  description?: string;
-  /**
-   * Slack agent profile (`features.agent_view.agent_description`).
-   * Defaults to `description`. Separate from the 140-character marketplace line.
-   */
-  agentDescription?: 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 };