@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/slack/auth.ts

@@ -1,127 +0,0 @@
-/**
- * Slack auth helpers — AuthContext builders for thread-scoped sessions.
- */
-
-import { samePrincipal } from "../../internal/auth.js";
-import { slackThreadKey } from "../../internal/slack-thread-key.js";
-import type { AuthContext } from "../../types.js";
-import type { SlackBinding, SlackBlockAction, SlackMessage, SlackRespondTo } from "./types.js";
-
-export type BuildSlackAuthArgs = {
-  channelId: string;
-  threadTs: string;
-  teamId?: string;
-  userId?: string;
-  userName?: string;
-  isBot?: boolean;
-  engagement?: string;
-  /** Defaults to `"thread"`. `"author"` appends `:{userId}` to the principal. */
-  respondTo?: SlackRespondTo;
-};
-
-/**
- * Build a Slack session principal.
- *
- * - `"thread"` (default): any participant can continue.
- * - `"author"`: only the starter (`…:{userId}`), same shape approvals already honor.
- */
-export function buildSlackAuthContext(args: BuildSlackAuthArgs): AuthContext {
-  const team = args.teamId ?? "unknown";
-  const respondTo = args.respondTo ?? "thread";
-  const conversation = slackThreadKey(args.channelId, args.threadTs);
-  const base = `slack:${team}:${conversation}`;
-  const authorScoped = respondTo === "author" && args.userId !== undefined && args.userId !== "";
-  const principalId = authorScoped ? `${base}:${args.userId}` : base;
-
-  const attributes: Record<string, string> = {
-    channel_id: args.channelId,
-    thread_ts: args.threadTs,
-  };
-  if (args.teamId !== undefined) {
-    attributes.team_id = args.teamId;
-  }
-  if (args.userId !== undefined) {
-    attributes.user_id = args.userId;
-  }
-  if (args.userName !== undefined) {
-    attributes.user_name = args.userName;
-  }
-  if (args.isBot === true) {
-    attributes.author_type = "bot";
-  }
-  if (args.engagement !== undefined) {
-    attributes.engagement = args.engagement;
-  }
-  return {
-    authenticator: "slack",
-    principalId,
-    principalType: "user",
-    attributes,
-  };
-}
-
-/**
- * Auth for a Slack user clicking an interactive Approve/Deny button.
- * Uses the clicker's identity for {@link SessionEngine.resolveApproval},
- * not the stored session principal (which would bypass ownership checks).
- */
-export function buildSlackInteractiveApprovalAuth(args: {
-  sessionAuth: AuthContext;
-  channelId: string;
-  threadTs: string;
-  teamId?: string;
-  clickingUserId: string;
-}): AuthContext {
-  const clickerAuth = buildSlackAuthContext({
-    channelId: args.channelId,
-    threadTs: args.threadTs,
-    teamId: args.teamId,
-    userId: args.clickingUserId,
-  });
-  if (samePrincipal(args.sessionAuth, clickerAuth)) {
-    return clickerAuth;
-  }
-  const userSuffix = `:${args.clickingUserId}`;
-  if (args.clickingUserId !== "" && args.sessionAuth.principalId.endsWith(userSuffix)) {
-    return {
-      ...clickerAuth,
-      principalId: args.sessionAuth.principalId,
-    };
-  }
-  return clickerAuth;
-}
-
-/**
- * Default auth for an `onBlockAction` dispatch: the click's thread-scoped
- * principal with the clicker in attributes, so replies in the same thread
- * continue the session and the clicker is the attributable user.
- */
-export function blockActionAuth(action: SlackBlockAction): AuthContext {
-  return buildSlackAuthContext({
-    channelId: action.channelId,
-    threadTs: action.threadTs,
-    teamId: action.teamId,
-    userId: action.userId,
-    userName: action.userName,
-  });
-}
-
-export function defaultSlackAuth(
-  message: SlackMessage,
-  ctx: SlackBinding,
-  options?: { engagement?: string; respondTo?: SlackRespondTo },
-): AuthContext | null {
-  if (message.author === undefined) {
-    return null;
-  }
-  return buildSlackAuthContext({
-    channelId: ctx.slack.channelId,
-    threadTs: ctx.slack.threadTs,
-    teamId: message.teamId,
-    userId: message.author.userId,
-    userName: message.author.userName,
-    isBot: message.author.isBot,
-    engagement: options?.engagement,
-    respondTo: options?.respondTo,
-  });
-}

package/src/channels/slack/blocks.ts

@@ -1,131 +0,0 @@
-/**
- * Block Kit building helpers shared by card-building agents.
- */
-
-/** Slack cap for one section block's mrkdwn text. */
-export const SLACK_SECTION_MRKDWN_MAX = 3000;
-
-/** Slack caps for a native `table` block (one table per message). */
-export const SLACK_TABLE_MAX_ROWS = 100;
-export const SLACK_TABLE_MAX_COLUMNS = 20;
-
-/**
- * Pack lines into as few mrkdwn section blocks as fit the 3000-char cap,
- * preserving order. Long lists (a full service fleet, a file inventory)
- * overflow a single section and make `chat.postMessage` refuse the whole
- * card with `invalid_blocks`.
- */
-export function mrkdwnSections(lines: readonly string[]): unknown[] {
-  const texts: string[] = [];
-  let current = "";
-  for (const raw of lines) {
-    // A single oversized line (one huge blob) hard-splits at the cap.
-    const parts: string[] = [];
-    for (let i = 0; i < Math.max(raw.length, 1); i += SLACK_SECTION_MRKDWN_MAX) {
-      parts.push(raw.slice(i, i + SLACK_SECTION_MRKDWN_MAX));
-    }
-    for (const line of parts) {
-      const next = current === "" ? line : `${current}\n${line}`;
-      if (next.length > SLACK_SECTION_MRKDWN_MAX && current !== "") {
-        texts.push(current);
-        current = line;
-      } else {
-        current = next;
-      }
-    }
-  }
-  if (current !== "") {
-    texts.push(current);
-  }
-  return texts.map(text => ({
-    type: "section",
-    text: { type: "mrkdwn", text },
-  }));
-}
-
-export type SlackTableAlign = "left" | "center" | "right";
-
-export type SlackTableColumnSetting = {
-  align?: SlackTableAlign;
-  is_wrapped?: boolean;
-};
-
-/** Cell types accepted by Slack's native `table` block. */
-export type SlackTableCell =
-  | { type: "raw_text"; text: string }
-  | {
-      type: "rich_text";
-      elements: Array<{
-        type: "rich_text_section";
-        elements: Array<
-          { type: "text"; text: string } | { type: "link"; url: string; text: string }
-        >;
-      }>;
-    };
-
-export type SlackTableBlock = {
-  type: "table";
-  rows: SlackTableCell[][];
-  column_settings?: SlackTableColumnSetting[];
-};
-
-/** Plain text cell (header or body). */
-export function slackRawTextCell(text: string): SlackTableCell {
-  return { type: "raw_text", text };
-}
-
-/** Linked cell via rich_text (preferred over mrkdwn `<url|label>` in tables). */
-export function slackLinkCell(args: { url: string; text: string }): SlackTableCell {
-  return {
-    type: "rich_text",
-    elements: [
-      {
-        type: "rich_text_section",
-        elements: [{ type: "link", url: args.url, text: args.text }],
-      },
-    ],
-  };
-}
-
-/**
- * Build a native Slack `table` block. First row is the header. Slack allows
- * at most one table block per message, 100 rows, and 20 columns — callers
- * should keep tables short.
- */
-export function slackTableBlock(args: {
-  headers: readonly string[];
-  rows: readonly (readonly SlackTableCell[])[];
-  columnSettings?: readonly SlackTableColumnSetting[];
-}): SlackTableBlock | undefined {
-  if (args.headers.length === 0) {
-    return undefined;
-  }
-  if (args.headers.length > SLACK_TABLE_MAX_COLUMNS) {
-    throw new Error(
-      `slackTableBlock: ${args.headers.length} columns exceeds Slack cap of ${SLACK_TABLE_MAX_COLUMNS}`,
-    );
-  }
-  // Header + body rows share the 100-row cap.
-  if (args.rows.length + 1 > SLACK_TABLE_MAX_ROWS) {
-    throw new Error(
-      `slackTableBlock: ${args.rows.length + 1} rows exceeds Slack cap of ${SLACK_TABLE_MAX_ROWS}`,
-    );
-  }
-  const columnCount = args.headers.length;
-  for (const [index, row] of args.rows.entries()) {
-    if (row.length !== columnCount) {
-      throw new Error(
-        `slackTableBlock: row ${index} has ${row.length} cells; expected ${columnCount}`,
-      );
-    }
-  }
-  const headerRow = args.headers.map(header => slackRawTextCell(header));
-  const block: SlackTableBlock = {
-    type: "table",
-    rows: [headerRow, ...args.rows.map(row => [...row])],
-  };
-  if (args.columnSettings !== undefined && args.columnSettings.length > 0) {
-    block.column_settings = [...args.columnSettings];
-  }
-  return block;
-}

package/src/channels/slack/bot-mentions.ts

@@ -1,318 +0,0 @@
-/**
- * Opt-in bot-to-bot mention wake (`engagement.botMentions`).
- *
- * Layered loop protection, any one of which blocks a runaway chain:
- * 1. Allowlist — only mentions from explicitly trusted bots wake the agent.
- * 2. Own-post filter — the agent's own posts never wake it (always on).
- * 3. Depth budget — delegation metadata carries a hop count; mentions
- *    without metadata count as depth 1. Default max is 2.
- * 4. Thread budgets — a sliding-window rate cap plus a lifetime total per
- *    thread, so undetected ping-pong between trusted bots terminates
- *    instead of merely slowing down.
- */
-
-import { postMessage } from "./api.js";
-import { defaultSlackLog, type SlackLog } from "./log.js";
-import type {
-  SlackBotMentionsOptions,
-  SlackBotToken,
-  SlackDelegationInfo,
-  SlackMessage,
-} from "./types.js";
-
-/** Slack message `metadata.event_type` for Agent SDK delegation posts. */
-export const SLACK_DELEGATION_METADATA_EVENT_TYPE = "agentkit_delegation";
-
-/** Default budgets for {@link SlackBotMentionsOptions}. */
-export const SLACK_BOT_MENTION_DEFAULTS = {
-  maxDepth: 2,
-  maxPerThreadPerHour: 5,
-  maxPerThreadTotal: 20,
-} as const;
-
-const THREAD_BUDGET_WINDOW_MS = 60 * 60 * 1000;
-/** Threads idle this long are evicted (their lifetime budget resets). */
-const THREAD_IDLE_EVICT_MS = 24 * 60 * 60 * 1000;
-/** Eviction sweep runs when the thread map grows past this many keys. */
-const THREAD_SWEEP_THRESHOLD = 512;
-
-function asRecord(value: unknown): Record<string, unknown> | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  return value as Record<string, unknown>;
-}
-
-/**
- * Parse delegation metadata off a raw Slack event (`event.metadata`).
- * Returns undefined for absent, foreign, or malformed metadata.
- */
-export function parseDelegationMetadata(event: unknown): SlackDelegationInfo | undefined {
-  const root = asRecord(event);
-  const metadata = asRecord(root?.metadata);
-  if (metadata === null || metadata.event_type !== SLACK_DELEGATION_METADATA_EVENT_TYPE) {
-    return undefined;
-  }
-  const payload = asRecord(metadata.event_payload);
-  if (payload === null) {
-    return undefined;
-  }
-  const depth =
-    typeof payload.depth === "number" && Number.isFinite(payload.depth)
-      ? Math.floor(payload.depth)
-      : undefined;
-  if (depth === undefined || depth < 1) {
-    return undefined;
-  }
-  const info: SlackDelegationInfo = { depth };
-  if (typeof payload.from_agent === "string" && payload.from_agent !== "") {
-    info.fromAgent = payload.from_agent;
-  }
-  if (typeof payload.origin_session_id === "string" && payload.origin_session_id !== "") {
-    info.originSessionId = payload.origin_session_id;
-  }
-  return info;
-}
-
-/** Build the Slack `metadata` body for an outbound delegation post. */
-export function buildDelegationMetadata(args: {
-  depth: number;
-  fromAgent?: string;
-  originSessionId?: string;
-}): Record<string, unknown> {
-  const payload: Record<string, unknown> = { depth: args.depth };
-  if (args.fromAgent !== undefined && args.fromAgent !== "") {
-    payload.from_agent = args.fromAgent;
-  }
-  if (args.originSessionId !== undefined && args.originSessionId !== "") {
-    payload.origin_session_id = args.originSessionId;
-  }
-  return {
-    event_type: SLACK_DELEGATION_METADATA_EVENT_TYPE,
-    event_payload: payload,
-  };
-}
-
-/**
- * Validate and normalize a `botMentions.allowFrom` list. Shared by channel
- * construction (fail at definition time) and the gate (fail at start).
- */
-export function normalizeBotMentionAllowlist(allowFrom: readonly string[]): string[] {
-  const entries = allowFrom.map(entry => entry.trim()).filter(entry => entry !== "");
-  if (entries.length === 0) {
-    throw new Error(
-      "slackChannel engagement.botMentions.allowFrom must list at least one bot id (B…) or bot user id (U…); there is no wildcard.",
-    );
-  }
-  return entries;
-}
-
-/**
- * Read `engagement.botMentions` options from the environment: a
- * comma-separated bot-id allowlist in `AGENT_DELEGATOR_SLACK_BOT_IDS` (or a
- * custom var). Returns undefined when unset, so channels can pass the
- * result straight through and stay bot-mention-free by default:
- *
- * ```ts
- * engagement: { botMentions: botMentionsFromEnv() }
- * ```
- */
-export function botMentionsFromEnv(
-  envVar = "AGENT_DELEGATOR_SLACK_BOT_IDS",
-): SlackBotMentionsOptions | undefined {
-  const allowFrom = (process.env[envVar] ?? "")
-    .split(",")
-    .map(entry => entry.trim())
-    .filter(entry => entry !== "");
-  return allowFrom.length === 0 ? undefined : { allowFrom };
-}
-
-export type SlackBotMentionVerdict =
-  | { allow: true; depth: number }
-  | { allow: false; reason: string };
-
-interface ThreadBudget {
-  /** Lifetime admitted wakes for this thread (until idle eviction). */
-  total: number;
-  /** Timestamps of recent admitted wakes (pruned to the window). */
-  recent: number[];
-  lastAtMs: number;
-}
-
-/**
- * Admission gate for bot-authored mentions. One instance per channel;
- * thread budgets are in-memory (reset on restart — acceptable, the depth
- * and allowlist layers do not depend on process state). Threads idle for
- * 24h are evicted, which also resets their lifetime budget.
- */
-export class SlackBotMentionGate {
-  private readonly allowFrom: Set<string>;
-  /** Compound entries: posting `bot_id` → allowed lowercase usernames. */
-  private readonly allowFromCompound: Map<string, Set<string>>;
-  private readonly maxDepth: number;
-  private readonly maxPerThreadPerHour: number;
-  private readonly maxPerThreadTotal: number;
-  private readonly windowMs: number;
-  private readonly threadBudgets = new Map<string, ThreadBudget>();
-  private readonly log: SlackLog;
-
-  constructor(
-    options: SlackBotMentionsOptions,
-    private readonly identity: { botUserId?: string; botId?: string },
-    args?: { log?: SlackLog; windowMs?: number },
-  ) {
-    if (identity.botUserId === undefined && identity.botId === undefined) {
-      throw new Error(
-        "SlackBotMentionGate requires the agent's own bot identity (auth.test) for loop safety.",
-      );
-    }
-    this.allowFrom = new Set();
-    this.allowFromCompound = new Map();
-    for (const entry of normalizeBotMentionAllowlist(options.allowFrom)) {
-      const separator = entry.indexOf(":");
-      if (separator <= 0 || separator === entry.length - 1) {
-        this.allowFrom.add(entry);
-        continue;
-      }
-      const botId = entry.slice(0, separator);
-      const username = entry.slice(separator + 1).toLowerCase();
-      const usernames = this.allowFromCompound.get(botId) ?? new Set();
-      usernames.add(username);
-      this.allowFromCompound.set(botId, usernames);
-    }
-    this.maxDepth = options.maxDepth ?? SLACK_BOT_MENTION_DEFAULTS.maxDepth;
-    this.maxPerThreadPerHour =
-      options.maxPerThreadPerHour ?? SLACK_BOT_MENTION_DEFAULTS.maxPerThreadPerHour;
-    this.maxPerThreadTotal =
-      options.maxPerThreadTotal ?? SLACK_BOT_MENTION_DEFAULTS.maxPerThreadTotal;
-    this.windowMs = args?.windowMs ?? THREAD_BUDGET_WINDOW_MS;
-    this.log = args?.log ?? defaultSlackLog;
-  }
-
-  /**
-   * Evaluate a bot-authored mention. Callers must only pass messages whose
-   * author `isBot`; human mentions never consult the gate. An `allow`
-   * verdict consumes thread budget.
-   */
-  evaluate(message: SlackMessage, nowMs: number = Date.now()): SlackBotMentionVerdict {
-    const author = message.author;
-    if (author === undefined || !author.isBot) {
-      return { allow: false, reason: "not bot-authored" };
-    }
-
-    // Own posts never wake the agent, allowlisted or not.
-    if (
-      (this.identity.botId !== undefined && author.botId === this.identity.botId) ||
-      (this.identity.botUserId !== undefined &&
-        author.userId !== "" &&
-        author.userId === this.identity.botUserId)
-    ) {
-      return { allow: false, reason: "own post (loop safety)" };
-    }
-
-    const compoundUsernames =
-      author.botId === undefined ? undefined : this.allowFromCompound.get(author.botId);
-    const allowed =
-      (author.botId !== undefined && this.allowFrom.has(author.botId)) ||
-      (author.userId !== "" && this.allowFrom.has(author.userId)) ||
-      // Compound entry: shared app bot_id + server-pinned username. Fails
-      // closed when the event carries no username.
-      (compoundUsernames !== undefined &&
-        author.userName !== undefined &&
-        compoundUsernames.has(author.userName.toLowerCase()));
-    if (!allowed) {
-      return { allow: false, reason: "author not in botMentions.allowFrom" };
-    }
-
-    const depth = message.delegation?.depth ?? 1;
-    if (depth > this.maxDepth) {
-      return {
-        allow: false,
-        reason: `delegation depth ${depth} exceeds max ${this.maxDepth}`,
-      };
-    }
-
-    this.maybeEvictIdleThreads(nowMs);
-    const key = `${message.channelId}:${message.threadTs}`;
-    const budget = this.threadBudgets.get(key) ?? {
-      total: 0,
-      recent: [],
-      lastAtMs: nowMs,
-    };
-    budget.recent = budget.recent.filter(atMs => atMs > nowMs - this.windowMs);
-    if (budget.total >= this.maxPerThreadTotal) {
-      return {
-        allow: false,
-        reason: `thread lifetime budget exhausted (${this.maxPerThreadTotal})`,
-      };
-    }
-    if (budget.recent.length >= this.maxPerThreadPerHour) {
-      return {
-        allow: false,
-        reason: `thread rate budget exhausted (${this.maxPerThreadPerHour}/window)`,
-      };
-    }
-    budget.total += 1;
-    budget.recent.push(nowMs);
-    budget.lastAtMs = nowMs;
-    this.threadBudgets.set(key, budget);
-    this.log.info("bot mention admitted", {
-      channel: message.channelId,
-      thread_ts: message.threadTs,
-      from_bot: author.botId ?? author.userId,
-      depth,
-      thread_total: budget.total,
-    });
-    return { allow: true, depth };
-  }
-
-  private maybeEvictIdleThreads(nowMs: number): void {
-    if (this.threadBudgets.size < THREAD_SWEEP_THRESHOLD) {
-      return;
-    }
-    for (const [key, budget] of this.threadBudgets) {
-      if (nowMs - budget.lastAtMs > THREAD_IDLE_EVICT_MS) {
-        this.threadBudgets.delete(key);
-      }
-    }
-  }
-}
-
-/**
- * Post an @mention of another bot with delegation metadata attached, so the
- * target's `engagement.botMentions` gate can read the hop count. Use this
- * from dispatcher tools instead of a bare `chat.postMessage`.
- */
-export async function postDelegationMention(args: {
-  botToken: SlackBotToken | undefined;
-  channelId: string;
-  /** Target bot's Slack *user* id (`U…`) — what `<@…>` mentions require. */
-  targetUserId: string;
-  text: string;
-  threadTs?: string;
-  /** Defaults to 1 (dispatcher woken by a human). */
-  depth?: number;
-  fromAgent?: string;
-  originSessionId?: string;
-}): Promise<{ ts: string }> {
-  const posted = await postMessage({
-    botToken: args.botToken,
-    channel: args.channelId,
-    text: `<@${args.targetUserId}> ${args.text}`.trim(),
-    threadTs: args.threadTs,
-    // Mention markup only notifies via mrkdwn `text`, and metadata must
-    // ride the same chat.postMessage call.
-    plainText: true,
-    metadata: buildDelegationMetadata({
-      depth: args.depth ?? 1,
-      fromAgent: args.fromAgent,
-      originSessionId: args.originSessionId,
-    }),
-  });
-  if (posted.ts === "") {
-    throw new Error(
-      "Slack delegation mention posted without a message ts; cannot track the handoff.",
-    );
-  }
-  return { ts: posted.ts };
-}