@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/slack/external-policy.ts

@@ -1,75 +0,0 @@
-/**
- * Workspace-membership checks for Agent SDK Slack agents.
- * Mirrors backend `isExternalSlackUser` (cloud-agent/slack/externalChannelPolicy).
- */
-
-import { callSlackApi } from "./api.js";
-import type { SlackBotToken } from "./types.js";
-
-type SlackUserInfo = {
-  team_id?: string;
-  is_stranger?: boolean;
-  is_restricted?: boolean;
-  is_ultra_restricted?: boolean;
-  enterprise_user?: { teams?: string[] };
-};
-
-/** Pure classifier over a `users.info` user object. Fails open to external. */
-export function classifySlackUserExternality(args: {
-  slackTeamId: string;
-  user: SlackUserInfo;
-}): boolean {
-  const { slackTeamId, user } = args;
-  if (
-    user.is_stranger === true ||
-    user.is_restricted === true ||
-    user.is_ultra_restricted === true
-  ) {
-    return true;
-  }
-  return (
-    user.team_id !== undefined &&
-    user.team_id !== slackTeamId &&
-    !(user.enterprise_user?.teams ?? []).includes(slackTeamId)
-  );
-}
-
-const classified = new Map<string, boolean>();
-
-export function resetExternalSenderCache(): void {
-  classified.clear();
-}
-
-/** Lookup + classify. Empty userId / API failure → external. Hits cache. */
-export async function isExternalSlackSender(args: {
-  botToken: SlackBotToken | undefined;
-  slackTeamId: string;
-  userId: string;
-}): Promise<boolean> {
-  if (args.userId === "") {
-    return true;
-  }
-  const key = `${args.slackTeamId}:${args.userId}`;
-  const cached = classified.get(key);
-  if (cached !== undefined) {
-    return cached;
-  }
-  try {
-    const result = await callSlackApi({
-      botToken: args.botToken,
-      operation: "users.info",
-      body: { user: args.userId },
-    });
-    if (result.ok !== true || result.user === undefined) {
-      return true;
-    }
-    const external = classifySlackUserExternality({
-      slackTeamId: args.slackTeamId,
-      user: result.user as SlackUserInfo,
-    });
-    classified.set(key, external);
-    return external;
-  } catch {
-    return true;
-  }
-}

package/src/channels/slack/footer.ts

@@ -1,106 +0,0 @@
-import { dashboardSessionUrl } from "../../dashboard-session-url.js";
-import type { HostContext } from "../../types.js";
-import { markdownToSlackMrkdwn, updateMessage } from "./api.js";
-import type { SlackBotToken, SoftSlackResult } from "./types.js";
-
-export type SlackReplyFooterContext = {
-  sessionId: string;
-  channelId: string;
-  threadTs: string;
-  text: string;
-  status: "completed" | "failed";
-  durationMs: number;
-  /** Turn paint passes the host so a footer can read durable state. */
-  host?: HostContext;
-};
-
-export type SlackReplyFooter =
-  | string
-  | ((ctx: SlackReplyFooterContext) => string | undefined | Promise<string | undefined>);
-
-export function turnDurationMs(startedAtMs: number | null | undefined): number {
-  if (startedAtMs === null || startedAtMs === undefined) {
-    return 0;
-  }
-  return Math.max(0, Date.now() - startedAtMs);
-}
-
-export function formatElapsed(ms: number): string {
-  if (ms < 10_000) {
-    return `${(ms / 1000).toFixed(1)}s`;
-  }
-  const total = Math.round(ms / 1000);
-  const h = Math.floor(total / 3600);
-  const m = Math.floor((total % 3600) / 60);
-  const s = total % 60;
-  if (h > 0) {
-    return `${h}h ${m}m ${s}s`;
-  }
-  if (m > 0) {
-    return `${m}m ${s}s`;
-  }
-  return `${s}s`;
-}
-
-export async function resolveSlackFooterBlocks(
-  footer: SlackReplyFooter | undefined,
-  ctx: SlackReplyFooterContext,
-): Promise<unknown[] | undefined> {
-  if (footer === undefined) {
-    return undefined;
-  }
-  const text = typeof footer === "function" ? await footer(ctx) : footer;
-  if (text === undefined || text.trim() === "") {
-    return undefined;
-  }
-  return [
-    {
-      type: "context",
-      elements: [{ type: "mrkdwn", text }],
-    },
-  ];
-}
-
-export function slackPostedReply(args: { text: string; footer?: unknown[] }): {
-  text: string;
-  blocks: unknown[] | undefined;
-} {
-  const text = markdownToSlackMrkdwn(args.text);
-  if (args.footer === undefined || args.footer.length === 0) {
-    return { text, blocks: undefined };
-  }
-  return {
-    text,
-    blocks: [{ type: "section", text: { type: "mrkdwn", text } }, ...args.footer],
-  };
-}
-
-export async function paintSlackFooter(args: {
-  footer: SlackReplyFooter | undefined;
-  ctx: SlackReplyFooterContext;
-  ts: string;
-  botToken: SlackBotToken | undefined;
-}): Promise<SoftSlackResult | undefined> {
-  const blocks = await resolveSlackFooterBlocks(args.footer, args.ctx);
-  if (blocks === undefined) {
-    return undefined;
-  }
-  const body = slackPostedReply({ text: args.ctx.text, footer: blocks });
-  return updateMessage({
-    botToken: args.botToken,
-    channel: args.ctx.channelId,
-    ts: args.ts,
-    text: body.text,
-    blocks: body.blocks,
-  });
-}
-
-export function slackSessionFooter(opts?: { slug?: string }): SlackReplyFooter {
-  return ctx => {
-    const url = dashboardSessionUrl(ctx.sessionId, { slug: opts?.slug });
-    if (url === undefined) {
-      return undefined;
-    }
-    return `<${url}|View session> · ${formatElapsed(ctx.durationMs)}`;
-  };
-}

package/src/channels/slack/inbound.ts

@@ -1,416 +0,0 @@
-/**
- * Parse Slack Events API payloads into structured inbound messages.
- */
-
-import { parseSlackFileRefs } from "./attachments.js";
-import { parseDelegationMetadata } from "./bot-mentions.js";
-import { slackApiMessageBody } from "./message-body.js";
-import type { SlackAuthor, SlackMessage } from "./types.js";
-
-type JsonRecord = Record<string, unknown>;
-
-function asRecord(value: unknown): JsonRecord | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  return value as JsonRecord;
-}
-
-function asString(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}
-
-/**
- * `type` / `subtype` of an Events API body's inner event, for log lines about
- * payloads no parser claimed (own-bot echoes, `message_changed`, pane
- * context changes). Never throws on odd shapes.
- */
-export function describeSlackEventShape(body: unknown): {
-  event_type: string;
-  event_subtype?: string;
-} {
-  const root = asRecord(body);
-  const event = asRecord(root?.event);
-  return {
-    event_type: asString(event?.type) ?? asString(root?.type) ?? "unknown",
-    event_subtype: asString(event?.subtype),
-  };
-}
-
-/** Strip common Slack mention tokens for a cleaner model prompt. */
-export function slackTextToMarkdown(text: string): string {
-  return text
-    .replace(/<@([A-Z0-9]+)>/g, "@$1")
-    .replace(/<#([A-Z0-9]+)(?:\|([^>]*))?>/g, (_m, _id, name: string) =>
-      name ? `#${name}` : "#channel",
-    )
-    .replace(/<([^|>]+)\|([^>]+)>/g, "$2")
-    .replace(/<([^>]+)>/g, "$1")
-    .trim();
-}
-
-function parseAuthor(event: JsonRecord): SlackAuthor | undefined {
-  const userId = asString(event.user);
-  const botId = asString(event.bot_id);
-  const isBot = botId !== undefined && botId.length > 0;
-  // Webhook-style bot posts can lack `user`; keep a bot author so the
-  // channel watch can attribute (and self-filter) them by `bot_id`.
-  if ((userId === undefined || userId === "") && !isBot) {
-    return undefined;
-  }
-  const userName = asString(event.username);
-  return {
-    userId: userId ?? "",
-    ...(userName === undefined ? {} : { userName }),
-    isBot,
-    ...(isBot ? { botId } : {}),
-  };
-}
-
-function buildSlackMessage(event: JsonRecord, teamId: string | undefined): SlackMessage | null {
-  const channelId = asString(event.channel);
-  const ts = asString(event.ts);
-  if (channelId === undefined || channelId === "" || ts === undefined || ts === "") {
-    return null;
-  }
-  const text = asString(event.text) ?? "";
-  // Alert feeds post an empty top-level `text` with the notification in
-  // `attachments` / `blocks`, so `body` (not `text`) is the message content.
-  const body = slackApiMessageBody(event);
-  const threadTs = asString(event.thread_ts) ?? ts;
-  const author = parseAuthor(event);
-  const files = parseSlackFileRefs(event);
-  return {
-    text,
-    body,
-    markdown: slackTextToMarkdown(body),
-    ts,
-    threadTs,
-    channelId,
-    ...(teamId === undefined ? {} : { teamId }),
-    ...(author === undefined ? {} : { author }),
-    files,
-  };
-}
-
-export interface ParseAppMentionOptions {
-  /**
-   * Keep bot-authored mentions instead of dropping them at parse time.
-   * The dispatch layer enforces the per-channel policy
-   * ({@link SlackBotMentionsOptions}: allowlist, depth, thread budget)
-   * and always drops the agent's own posts.
-   */
-  includeBotAuthored?: boolean;
-}
-
-export function parseAppMentionEvent(
-  body: unknown,
-  options?: ParseAppMentionOptions,
-): SlackMessage | null {
-  const root = asRecord(body);
-  if (root === null || root.type !== "event_callback") {
-    return null;
-  }
-  const event = asRecord(root.event);
-  if (event === null || event.type !== "app_mention") {
-    return null;
-  }
-  // Drop bot-authored mentions (mirrors DM filtering) to avoid loops,
-  // unless the caller opted into the gated bot-mention path.
-  const botId = asString(event.bot_id);
-  const isBotAuthored = botId !== undefined && botId.length > 0;
-  if (isBotAuthored && options?.includeBotAuthored !== true) {
-    return null;
-  }
-  const message = buildSlackMessage(event, asString(root.team_id));
-  if (message === null || !isBotAuthored) {
-    return message;
-  }
-  const delegation = parseDelegationMetadata(event);
-  return delegation === undefined ? message : { ...message, delegation };
-}
-
-export interface SlackAppHomeOpened {
-  channelId: string;
-  tab: string;
-  userId?: string;
-  teamId?: string;
-}
-
-/** Slack fires this when a user opens the app Home or Messages tab. */
-export function parseAppHomeOpened(body: unknown): SlackAppHomeOpened | null {
-  const root = asRecord(body);
-  if (root === null || root.type !== "event_callback") {
-    return null;
-  }
-  const event = asRecord(root.event);
-  if (event === null || event.type !== "app_home_opened") {
-    return null;
-  }
-  const channelId = asString(event.channel);
-  const tab = asString(event.tab);
-  if (channelId === undefined || channelId === "" || tab === undefined || tab === "") {
-    return null;
-  }
-  const userId = asString(event.user);
-  const teamId = asString(root.team_id) ?? asString(event.team_id);
-  return {
-    channelId,
-    tab,
-    userId: userId === undefined || userId === "" ? undefined : userId,
-    teamId: teamId === undefined || teamId === "" ? undefined : teamId,
-  };
-}
-
-export interface SlackAssistantThreadStarted {
-  channelId: string;
-  threadTs: string;
-  userId?: string;
-  teamId?: string;
-}
-
-/** Slack fires this when a user opens the assistant pane. No model turn. */
-export function parseAssistantThreadStarted(body: unknown): SlackAssistantThreadStarted | null {
-  const root = asRecord(body);
-  if (root === null || root.type !== "event_callback") {
-    return null;
-  }
-  const event = asRecord(root.event);
-  if (event === null || event.type !== "assistant_thread_started") {
-    return null;
-  }
-  const thread = asRecord(event.assistant_thread);
-  if (thread === null) {
-    return null;
-  }
-  const channelId = asString(thread.channel_id);
-  const threadTs = asString(thread.thread_ts);
-  if (channelId === undefined || channelId === "" || threadTs === undefined || threadTs === "") {
-    return null;
-  }
-  const userId = asString(thread.user_id);
-  const teamId = asString(root.team_id) ?? asString(event.team_id);
-  return {
-    channelId,
-    threadTs,
-    userId: userId === undefined || userId === "" ? undefined : userId,
-    teamId: teamId === undefined || teamId === "" ? undefined : teamId,
-  };
-}
-
-/**
- * The receiving app's own bot user id from an Events API envelope. Slack
- * stamps `authorizations[]` on every `event_callback` with the installed
- * bot user the delivery is for, so a hosted guest learns its identity from
- * the verified body without an `auth.test` round trip.
- */
-export function parseEventBodyBotUserId(body: unknown): string | undefined {
-  const root = asRecord(body);
-  if (root === null || root.type !== "event_callback") {
-    return undefined;
-  }
-  if (!Array.isArray(root.authorizations)) {
-    return undefined;
-  }
-  for (const entry of root.authorizations) {
-    const authorization = asRecord(entry);
-    const userId = asString(authorization?.user_id);
-    if (userId !== undefined && userId !== "") {
-      return userId;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Parse DM / IM messages. More generous than a strict channel_type check:
- * accepts `channel_type === "im"` or channel ids starting with `D`, and
- * treats threaded follow-ups (`thread_ts` present) as continuations.
- */
-export function parseDirectMessageEvent(body: unknown): SlackMessage | null {
-  const root = asRecord(body);
-  if (root === null || root.type !== "event_callback") {
-    return null;
-  }
-  const event = asRecord(root.event);
-  if (event === null || event.type !== "message") {
-    return null;
-  }
-
-  const channelId = asString(event.channel) ?? "";
-  const channelType = asString(event.channel_type);
-  const isIm =
-    channelType === "im" ||
-    (channelId.startsWith("D") && channelType !== "channel" && channelType !== "group");
-  if (!isIm) {
-    return null;
-  }
-
-  const subtype = asString(event.subtype);
-  if (subtype !== undefined && subtype.length > 0 && subtype !== "file_share") {
-    return null;
-  }
-  const botId = asString(event.bot_id);
-  if (botId !== undefined && botId.length > 0) {
-    return null;
-  }
-  return buildSlackMessage(event, asString(root.team_id));
-}
-
-/**
- * Parse a message `reaction_added` event into a synthetic Slack message.
- * The reacted-to timestamp becomes the thread root so normal hydration loads
- * the complete thread before the dedicated handler dispatches a turn.
- */
-export function parseReactionAddedEvent(body: unknown): SlackMessage | null {
-  const root = asRecord(body);
-  if (root === null || root.type !== "event_callback") {
-    return null;
-  }
-  const event = asRecord(root.event);
-  if (event === null || event.type !== "reaction_added") {
-    return null;
-  }
-  const item = asRecord(event.item);
-  if (item === null || item.type !== "message") {
-    return null;
-  }
-  const userId = asString(event.user);
-  const reaction = asString(event.reaction);
-  const channelId = asString(item.channel);
-  const threadTs = asString(item.ts);
-  if (
-    userId === undefined ||
-    userId === "" ||
-    reaction === undefined ||
-    reaction === "" ||
-    channelId === undefined ||
-    channelId === "" ||
-    threadTs === undefined ||
-    threadTs === ""
-  ) {
-    return null;
-  }
-  const ts = asString(event.event_ts) ?? threadTs;
-  const text = `Slack user <@${userId}> added :${reaction}: to this thread.`;
-  const itemUserId = asString(event.item_user);
-  const teamId = asString(root.team_id);
-  return {
-    text,
-    body: text,
-    markdown: slackTextToMarkdown(text),
-    ts,
-    threadTs,
-    channelId,
-    ...(teamId === undefined ? {} : { teamId }),
-    author: {
-      userId,
-      isBot: false,
-    },
-    reaction: {
-      name: reaction,
-      ...(itemUserId === undefined ? {} : { itemUserId }),
-    },
-  };
-}
-
-/** Parsed `message.channels` / `message.groups` event for channel watch. */
-export type SlackChannelMessageEvent =
-  | { kind: "post"; message: SlackMessage }
-  | { kind: "edited"; message: SlackMessage }
-  | { kind: "deleted"; channelId: string; ts: string };
-
-export interface ParseChannelMessageOptions {
-  /**
-   * Keep bot-authored posts (including `subtype: "bot_message"` webhook
-   * posts) instead of dropping them at parse time. The channel watch
-   * enforces its own per-channel policy ({@link SlackChannelPostsOptions.includeBotPosts})
-   * and always drops the watching bot's own posts.
-   */
-  includeBotAuthored?: boolean;
-}
-
-/**
- * Parse channel / private-channel message events for the opt-in channel
- * watch. Accepts `channel_type === "channel" | "group"` (or `C…`/`G…`
- * channel ids when the type is absent). Bot-authored messages are dropped
- * (loop safety) unless `options.includeBotAuthored` is set; edits and
- * deletions are surfaced so a debounce window can update or cancel a
- * pending dispatch.
- */
-export function parseChannelMessageEvent(
-  body: unknown,
-  options?: ParseChannelMessageOptions,
-): SlackChannelMessageEvent | null {
-  const root = asRecord(body);
-  if (root === null || root.type !== "event_callback") {
-    return null;
-  }
-  const event = asRecord(root.event);
-  if (event === null || event.type !== "message") {
-    return null;
-  }
-
-  const channelId = asString(event.channel) ?? "";
-  const channelType = asString(event.channel_type);
-  const isChannel =
-    channelType === "channel" ||
-    channelType === "group" ||
-    (channelType === undefined && (channelId.startsWith("C") || channelId.startsWith("G")));
-  if (!isChannel || channelId === "") {
-    return null;
-  }
-
-  const teamId = asString(root.team_id);
-  const subtype = asString(event.subtype) ?? "";
-  const includeBots = options?.includeBotAuthored === true;
-
-  if (subtype === "message_deleted") {
-    const deletedTs = asString(event.deleted_ts) ?? "";
-    return deletedTs === "" ? null : { kind: "deleted", channelId, ts: deletedTs };
-  }
-
-  if (subtype === "message_changed") {
-    const nested = asRecord(event.message);
-    if (nested === null) {
-      return null;
-    }
-    const botId = asString(nested.bot_id);
-    if (!includeBots && botId !== undefined && botId.length > 0) {
-      return null;
-    }
-    const message = buildSlackMessage({ ...nested, channel: channelId }, teamId);
-    return message === null ? null : { kind: "edited", message };
-  }
-
-  const allowedSubtypes = includeBots ? ["", "file_share", "bot_message"] : ["", "file_share"];
-  if (!allowedSubtypes.includes(subtype)) {
-    return null;
-  }
-  const botId = asString(event.bot_id);
-  if (!includeBots && botId !== undefined && botId.length > 0) {
-    return null;
-  }
-  const message = buildSlackMessage(event, teamId);
-  return message === null ? null : { kind: "post", message };
-}
-
-export function formatSlackContextBlock(args: {
-  userId: string;
-  userName?: string;
-  channelId: string;
-  threadTs: string;
-  teamId?: string;
-}): string {
-  const lines = ["<slack_context>", `user_id: ${args.userId}`];
-  if (args.userName !== undefined) {
-    lines.push(`user_name: ${args.userName}`);
-  }
-  lines.push(`channel_id: ${args.channelId}`);
-  lines.push(`thread_ts: ${args.threadTs}`);
-  if (args.teamId !== undefined) {
-    lines.push(`team_id: ${args.teamId}`);
-  }
-  lines.push("</slack_context>");
-  return lines.join("\n");
-}

package/src/channels/slack/index.ts

@@ -1,53 +0,0 @@
-/**
- * Slack platform channel pack for agent-serve.
- *
- * ```ts
- * import { slackChannel } from "@cursor/bdk/channels/slack";
- *
- * // Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN
- * export default slackChannel();
- *
- * // Multi-agent serve: one Slack app per agent
- * export default slackChannel({ envPrefix: "MY_AGENT" });
- * // → MY_AGENT_SLACK_BOT_TOKEN + MY_AGENT_SLACK_APP_TOKEN
- * ```
- */
-
-export { dashboardSessionUrl } from "../../dashboard-session-url.js";
-export * from "./api.js";
-export * from "./approvals.js";
-export * from "./assistant.js";
-export * from "./attachments.js";
-export * from "./auth.js";
-export * from "./blocks.js";
-export * from "./bot-mentions.js";
-export * from "./channel-watch.js";
-export * from "./code-fences.js";
-export * from "./constants.js";
-export * from "./credentials.js";
-export * from "./defaults.js";
-export * from "./dispatch.js";
-export * from "./doctor.js";
-export * from "./eval-directive.js";
-export * from "./event-id-dedupe.js";
-export * from "./external-policy.js";
-export * from "./footer.js";
-export * from "./inbound.js";
-export * from "./init.js";
-export * from "./interactive.js";
-export * from "./links.js";
-export * from "./log.js";
-export * from "./manifest.js";
-export * from "./message-body.js";
-export * from "./nudge-carrier.js";
-export * from "./nudge-store.js";
-export * from "./pr-ref.js";
-export * from "./setup.js";
-export * from "./slack-channel.js";
-export * from "./socket-mode.js";
-export * from "./stop.js";
-export * from "./stream.js";
-export * from "./thread-context.js";
-export * from "./tool-approval-events.js";
-export { defaultToolCardDetails } from "./tool-cards.js";
-export * from "./types.js";