@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/slack/thread-context.ts

@@ -1,485 +0,0 @@
-/**
- * Fetch prior Slack thread messages and format them for the model prompt.
- *
- * Cold-start mentions (`@agent what happened here?`) only carry the mention
- * text; the parent alert / earlier replies live in `conversations.replies`.
- */
-
-import { callSlackApiSoft } from "./api.js";
-import { slackTextToMarkdown } from "./inbound.js";
-import { defaultSlackLog, type SlackLog } from "./log.js";
-import { slackApiMessageBody } from "./message-body.js";
-import type { SlackBotToken, SoftSlackResult } from "./types.js";
-
-/** Cap replies fetched from Slack (plus the parent). */
-const DEFAULT_REPLY_LIMIT = 50;
-/** Soft cap on the formatted block so we don't blow the prompt. */
-const DEFAULT_MAX_CHARS = 12_000;
-/** Slack pages `conversations.replies` oldest-first; bound pagination. */
-const REPLIES_PAGE_LIMIT = 200;
-const REPLIES_MAX_PAGES = 5;
-
-function excludeTimestampSet(
-  excludeTs: string | readonly string[] | undefined,
-): Set<string> | undefined {
-  if (excludeTs === undefined) {
-    return undefined;
-  }
-  if (typeof excludeTs === "string") {
-    return new Set([excludeTs]);
-  }
-  const set = new Set<string>();
-  for (const ts of excludeTs) {
-    if (ts !== "") {
-      set.add(ts);
-    }
-  }
-  return set.size > 0 ? set : undefined;
-}
-
-/** Keep the thread root plus the newest replies when over the fetch cap. */
-export function trimThreadMessagesForPrompt(
-  messages: JsonRecord[],
-  options: {
-    threadTs: string;
-    limit: number;
-    excludeTs?: string | readonly string[];
-  },
-): JsonRecord[] {
-  const exclude = excludeTimestampSet(options.excludeTs);
-  const filtered = messages.filter(message => {
-    const ts = asString(message.ts);
-    if (ts === undefined || ts === "") {
-      return false;
-    }
-    if (exclude !== undefined && exclude.has(ts)) {
-      return false;
-    }
-    return slackApiMessageBody(message).trim() !== "";
-  });
-  if (filtered.length <= options.limit) {
-    return filtered;
-  }
-  const parentIndex = filtered.findIndex(message => asString(message.ts) === options.threadTs);
-  const parent = parentIndex >= 0 ? filtered[parentIndex]! : undefined;
-  const withoutParent =
-    parentIndex >= 0 ? filtered.filter((_message, index) => index !== parentIndex) : filtered;
-  const tail = withoutParent.slice(
-    Math.max(0, withoutParent.length - (options.limit - (parent === undefined ? 0 : 1))),
-  );
-  if (parent === undefined) {
-    return tail;
-  }
-  if (tail.some(message => asString(message.ts) === options.threadTs)) {
-    return tail;
-  }
-  return [parent, ...tail];
-}
-
-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;
-}
-
-function formatThreadEntry(message: JsonRecord, role: "parent" | "reply"): string {
-  const ts = asString(message.ts) ?? "?";
-  const userId = asString(message.user);
-  const botId = asString(message.bot_id);
-  const username = asString(message.username);
-  const who =
-    userId !== undefined && userId !== ""
-      ? userId
-      : botId !== undefined && botId !== ""
-        ? `bot:${botId}${username !== undefined ? ` (${username})` : ""}`
-        : (username ?? "unknown");
-  const body = slackTextToMarkdown(slackApiMessageBody(message));
-  if (body === "") {
-    return `[${role}] ${who} @ ${ts}:\n(empty)`;
-  }
-  return `[${role}] ${who} @ ${ts}:\n${body}`;
-}
-
-function compareSlackTs(a: string, b: string): number {
-  const [aSec = "0", aFrac = "0"] = a.split(".");
-  const [bSec = "0", bFrac = "0"] = b.split(".");
-  const zero = BigInt(0);
-  const sec = BigInt(aSec) - BigInt(bSec);
-  if (sec !== zero) {
-    return sec < zero ? -1 : 1;
-  }
-  const frac = BigInt(aFrac.padEnd(6, "0").slice(0, 6)) - BigInt(bFrac.padEnd(6, "0").slice(0, 6));
-  if (frac === zero) {
-    return 0;
-  }
-  return frac < zero ? -1 : 1;
-}
-
-/** True when `ts` is strictly after `afterTs`. */
-export function isSlackTsAfter(ts: string, afterTs: string): boolean {
-  return compareSlackTs(ts, afterTs) > 0;
-}
-
-/**
- * Merge triggering messages (by ts) into a replies window when Slack lag
- * omits them from `conversations.replies`.
- */
-export function mergeThreadMessagesByTs(
-  messages: JsonRecord[],
-  extras: readonly JsonRecord[],
-): JsonRecord[] {
-  const byTs = new Map<string, JsonRecord>();
-  for (const message of messages) {
-    const ts = asString(message.ts);
-    if (ts !== undefined && ts !== "") {
-      byTs.set(ts, message);
-    }
-  }
-  for (const extra of extras) {
-    const ts = asString(extra.ts);
-    if (ts === undefined || ts === "") {
-      continue;
-    }
-    if (!byTs.has(ts)) {
-      byTs.set(ts, extra);
-    }
-  }
-  return [...byTs.values()].sort((a, b) =>
-    compareSlackTs(asString(a.ts) ?? "0", asString(b.ts) ?? "0"),
-  );
-}
-
-/**
- * Latest bot-authored message ts in a thread (own posts), used as the warm
- * delta watermark when channel state has not recorded one yet.
- */
-export function findLastBotMessageTs(
-  messages: readonly JsonRecord[],
-  options?: {
-    botUserId?: string;
-    botId?: string;
-  },
-): string | undefined {
-  const restrictToSelf =
-    (options?.botUserId !== undefined && options.botUserId !== "") ||
-    (options?.botId !== undefined && options.botId !== "");
-  let last: string | undefined;
-  for (const message of messages) {
-    const ts = asString(message.ts);
-    if (ts === undefined || ts === "") {
-      continue;
-    }
-    const userId = asString(message.user);
-    const botId = asString(message.bot_id);
-    const isBot = restrictToSelf
-      ? (options?.botUserId !== undefined &&
-          options.botUserId !== "" &&
-          userId !== undefined &&
-          userId === options.botUserId) ||
-        (options?.botId !== undefined &&
-          options.botId !== "" &&
-          botId !== undefined &&
-          botId === options.botId)
-      : message.subtype === "bot_message" ||
-        (botId !== undefined && botId !== "") ||
-        (options?.botUserId !== undefined &&
-          userId !== undefined &&
-          userId === options.botUserId) ||
-        (options?.botId !== undefined && botId !== undefined && botId === options.botId);
-    if (!isBot) {
-      continue;
-    }
-    if (last === undefined || isSlackTsAfter(ts, last)) {
-      last = ts;
-    }
-  }
-  return last;
-}
-
-/** Messages strictly after `afterTs`, excluding listed timestamps. */
-export function selectThreadDeltaMessages(
-  messages: JsonRecord[],
-  options: {
-    afterTs?: string;
-    excludeTs?: string | readonly string[];
-  },
-): JsonRecord[] {
-  const exclude = excludeTimestampSet(options.excludeTs);
-  const afterTs = options.afterTs?.trim() ?? "";
-  return messages.filter(message => {
-    const ts = asString(message.ts);
-    if (ts === undefined || ts === "") {
-      return false;
-    }
-    if (exclude !== undefined && exclude.has(ts)) {
-      return false;
-    }
-    if (afterTs !== "" && !isSlackTsAfter(ts, afterTs)) {
-      return false;
-    }
-    return slackApiMessageBody(message).trim() !== "";
-  });
-}
-
-export function formatSlackThreadContextBlock(
-  messages: JsonRecord[],
-  options?: {
-    threadTs?: string;
-    excludeTs?: string | readonly string[];
-    maxChars?: number;
-  },
-): string | undefined {
-  const threadTs = options?.threadTs;
-  const maxChars = options?.maxChars ?? DEFAULT_MAX_CHARS;
-  const prior =
-    threadTs !== undefined && threadTs !== ""
-      ? trimThreadMessagesForPrompt(messages, {
-          threadTs,
-          limit: DEFAULT_REPLY_LIMIT,
-          excludeTs: options?.excludeTs,
-        })
-      : messages.filter(message => {
-          const ts = asString(message.ts);
-          if (ts === undefined || ts === "") {
-            return false;
-          }
-          const exclude = excludeTimestampSet(options?.excludeTs);
-          if (exclude !== undefined && exclude.has(ts)) {
-            return false;
-          }
-          return slackApiMessageBody(message).trim() !== "";
-        });
-  if (prior.length === 0) {
-    return undefined;
-  }
-
-  const lines = ["<slack_thread>"];
-  for (let i = 0; i < prior.length; i++) {
-    const ts = asString(prior[i]!.ts);
-    const entryRole =
-      threadTs !== undefined
-        ? ts === threadTs
-          ? "parent"
-          : "reply"
-        : i === 0
-          ? "parent"
-          : "reply";
-    lines.push(formatThreadEntry(prior[i]!, entryRole));
-    lines.push("");
-  }
-  lines.push("</slack_thread>");
-
-  let block = lines.join("\n").trimEnd();
-  if (block.length > maxChars) {
-    block = `${block.slice(0, Math.max(0, maxChars - 80))}\n…(truncated; older thread content omitted)\n</slack_thread>`;
-  }
-  return block;
-}
-
-export function formatSlackThreadDeltaBlock(
-  messages: JsonRecord[],
-  options?: {
-    excludeTs?: string | readonly string[];
-    afterTs?: string;
-    maxChars?: number;
-  },
-): string | undefined {
-  const maxChars = options?.maxChars ?? DEFAULT_MAX_CHARS;
-  const delta = selectThreadDeltaMessages(messages, {
-    afterTs: options?.afterTs,
-    excludeTs: options?.excludeTs,
-  });
-  if (delta.length === 0) {
-    return undefined;
-  }
-  const lines = [
-    "<slack_thread_delta>",
-    "Thread messages since your last post (or the latest new replies):",
-    "",
-  ];
-  for (const message of delta) {
-    lines.push(formatThreadEntry(message, "reply"));
-    lines.push("");
-  }
-  lines.push("</slack_thread_delta>");
-  let block = lines.join("\n").trimEnd();
-  if (block.length > maxChars) {
-    block = `${block.slice(0, Math.max(0, maxChars - 80))}\n…(truncated)\n</slack_thread_delta>`;
-  }
-  return block;
-}
-
-async function fetchThreadMessages(args: {
-  botToken: SlackBotToken;
-  channelId: string;
-  threadTs: string;
-  log: SlackLog;
-}): Promise<JsonRecord[] | undefined> {
-  const allMessages: JsonRecord[] = [];
-  let cursor: string | undefined;
-  let exhaustedPageBudget = false;
-  try {
-    for (let page = 0; page < REPLIES_MAX_PAGES; page++) {
-      const result: SoftSlackResult = await callSlackApiSoft({
-        botToken: args.botToken,
-        operation: "conversations.replies",
-        body: {
-          channel: args.channelId,
-          ts: args.threadTs,
-          limit: REPLIES_PAGE_LIMIT,
-          inclusive: true,
-          ...(cursor === undefined ? {} : { cursor }),
-        },
-      });
-      if (!result.ok) {
-        args.log.warn("thread context fetch not-ok", {
-          channel: args.channelId,
-          thread_ts: args.threadTs,
-          error: result.error,
-        });
-        return undefined;
-      }
-      const pageMessages = Array.isArray(result.messages)
-        ? result.messages.map(asRecord).filter((m): m is JsonRecord => m !== null)
-        : [];
-      allMessages.push(...pageMessages);
-      const nextCursor =
-        typeof result.response_metadata === "object" &&
-        result.response_metadata !== null &&
-        !Array.isArray(result.response_metadata)
-          ? asString((result.response_metadata as JsonRecord).next_cursor)
-          : undefined;
-      const hasMore = result.has_more === true;
-      cursor = nextCursor !== undefined && nextCursor !== "" ? nextCursor : undefined;
-      if (!hasMore || cursor === undefined) {
-        break;
-      }
-      if (page === REPLIES_MAX_PAGES - 1) {
-        exhaustedPageBudget = true;
-      }
-    }
-  } catch (error) {
-    args.log.warn("thread context fetch failed", {
-      channel: args.channelId,
-      thread_ts: args.threadTs,
-      error: error instanceof Error ? error.message : String(error),
-    });
-    return undefined;
-  }
-
-  if (exhaustedPageBudget) {
-    args.log.warn("thread context pagination budget exhausted", {
-      channel: args.channelId,
-      thread_ts: args.threadTs,
-      fetched: allMessages.length,
-    });
-  }
-  return allMessages;
-}
-
-/**
- * Load prior messages in a Slack thread and return a prompt context block.
- * Soft-fails (returns undefined) when credentials are missing or the API errors.
- */
-export async function loadSlackThreadContextBlock(args: {
-  botToken: SlackBotToken | undefined;
-  channelId: string;
-  threadTs: string;
-  excludeTs?: string | readonly string[];
-  log?: SlackLog;
-  limit?: number;
-  maxChars?: number;
-  /** Extra messages merged by ts when Slack replies lag (Benny parity). */
-  mergeMessages?: readonly JsonRecord[];
-}): Promise<string | undefined> {
-  const log = args.log ?? defaultSlackLog;
-  if (args.botToken === undefined) {
-    return undefined;
-  }
-  if (args.channelId === "" || args.threadTs === "") {
-    return undefined;
-  }
-
-  const replyLimit = args.limit ?? DEFAULT_REPLY_LIMIT;
-  const fetched = await fetchThreadMessages({
-    botToken: args.botToken,
-    channelId: args.channelId,
-    threadTs: args.threadTs,
-    log,
-  });
-  if (fetched === undefined) {
-    return undefined;
-  }
-  const allMessages =
-    args.mergeMessages === undefined || args.mergeMessages.length === 0
-      ? fetched
-      : mergeThreadMessagesByTs(fetched, args.mergeMessages);
-
-  const trimmed = trimThreadMessagesForPrompt(allMessages, {
-    threadTs: args.threadTs,
-    limit: replyLimit,
-    excludeTs: args.excludeTs,
-  });
-  return formatSlackThreadContextBlock(trimmed, {
-    threadTs: args.threadTs,
-    maxChars: args.maxChars,
-  });
-}
-
-/**
- * Warm-turn delta: messages since the last bot post (or all new replies when
- * the watermark is unknown), with optional merge-by-ts for the triggering ask.
- */
-export async function loadSlackThreadDeltaBlock(args: {
-  botToken: SlackBotToken | undefined;
-  channelId: string;
-  threadTs: string;
-  /** Watermark from channel state (`lastBotMessageTs`). */
-  afterTs?: string;
-  excludeTs?: string | readonly string[];
-  log?: SlackLog;
-  maxChars?: number;
-  mergeMessages?: readonly JsonRecord[];
-  botUserId?: string;
-  botId?: string;
-}): Promise<string | undefined> {
-  const log = args.log ?? defaultSlackLog;
-  if (args.botToken === undefined) {
-    return undefined;
-  }
-  if (args.channelId === "" || args.threadTs === "") {
-    return undefined;
-  }
-  const fetched = await fetchThreadMessages({
-    botToken: args.botToken,
-    channelId: args.channelId,
-    threadTs: args.threadTs,
-    log,
-  });
-  if (fetched === undefined) {
-    return undefined;
-  }
-  const allMessages =
-    args.mergeMessages === undefined || args.mergeMessages.length === 0
-      ? fetched
-      : mergeThreadMessagesByTs(fetched, args.mergeMessages);
-  const afterTs =
-    args.afterTs !== undefined && args.afterTs.trim() !== ""
-      ? args.afterTs.trim()
-      : findLastBotMessageTs(allMessages, {
-          ...(args.botUserId === undefined ? {} : { botUserId: args.botUserId }),
-          ...(args.botId === undefined ? {} : { botId: args.botId }),
-        });
-  return formatSlackThreadDeltaBlock(allMessages, {
-    afterTs,
-    excludeTs: args.excludeTs,
-    maxChars: args.maxChars,
-  });
-}

package/src/channels/slack/tool-approval-events.ts

@@ -1,233 +0,0 @@
-/**
- * Slack surface for human-in-the-loop tool approvals.
- *
- * Or compose with {@link buildDefaultEvents} (or your own handlers). When
- * composing by hand, also set `slackChannel({ interactivity: true })` (or
- * `toolApprovals: true`) so Socket Mode routes Approve/Deny clicks —
- * otherwise cards post but button presses are ACKed and ignored:
- *
- * ```ts
- * events: {
- *   ...buildDefaultEvents({ credentials }),
- *   ...buildToolApprovalEvents({ credentials }),
- * }
- * ```
- *
- * Or opt in via `slackChannel({ toolApprovals: true })`.
- * Park/resume itself is the framework HITL primitive (`needsApproval`);
- * this pack only delivers Approve/Deny in Slack.
- */
-
-import type { ChannelEventHandlers } from "../../types.js";
-import { postMessage, setThreadStatus, updateMessage } from "./api.js";
-import {
-  authThreadStatus,
-  buildApprovalBlocks,
-  buildAuthBlocks,
-  buildResolvedApprovalBlocks,
-  buildResolvedAuthBlocks,
-} from "./approvals.js";
-import { SLACK_DEFAULT_LOADING_MESSAGES } from "./constants.js";
-import { defaultSlackLog, type SlackLog } from "./log.js";
-import type { SlackChannelState, SlackCredentials } from "./types.js";
-
-export interface BuildToolApprovalEventsOptions {
-  credentials?: SlackCredentials;
-  /** Resolved per-call so channel onStart can rebind the server logger. */
-  getLog?: () => SlackLog;
-  /**
-   * Progress chip around park/resume. Defaults to `true`.
-   * When false, park writes no chip and resolve clears it.
-   */
-  status?: boolean;
-}
-
-/**
- * Stream-event handlers that post Block Kit Approve/Deny cards and
- * update them when approval is resolved (HTTP, playground, or Slack).
- */
-export function buildToolApprovalEvents(
-  options: BuildToolApprovalEventsOptions = {},
-): ChannelEventHandlers<SlackChannelState> {
-  const botToken = options.credentials?.botToken;
-  const getLog = options.getLog ?? (() => defaultSlackLog);
-  const status = options.status !== false;
-
-  async function resolveChip(state: SlackChannelState): Promise<void> {
-    if (state.channelId === null || state.threadTs === null) {
-      return;
-    }
-    if (status) {
-      await setThreadStatus({
-        botToken,
-        channelId: state.channelId,
-        threadTs: state.threadTs,
-        status: "Working…",
-        loadingMessages: [...SLACK_DEFAULT_LOADING_MESSAGES],
-      });
-      return;
-    }
-    await setThreadStatus({
-      botToken,
-      channelId: state.channelId,
-      threadTs: state.threadTs,
-      status: "",
-    });
-  }
-
-  return {
-    async "action.approval_requested"(event, channel, ctx) {
-      const log = getLog();
-      const state = channel.state;
-      if (state.channelId === null || state.threadTs === null) {
-        return;
-      }
-      const blocks = buildApprovalBlocks({
-        sessionId: ctx.session.id,
-        callId: event.data.callId,
-        toolName: event.data.toolName,
-        args: event.data.args,
-      });
-      try {
-        const posted = await postMessage({
-          botToken,
-          channel: state.channelId,
-          threadTs: state.threadTs,
-          text: `Approval required for \`${event.data.toolName}\``,
-          blocks,
-        });
-        channel.state.approvalMessageByCallId = {
-          ...(state.approvalMessageByCallId ?? {}),
-          [event.data.callId]: posted.ts,
-        };
-        if (status) {
-          await setThreadStatus({
-            botToken,
-            channelId: state.channelId,
-            threadTs: state.threadTs,
-            status: "Awaiting approval…",
-            loadingMessages: ["Awaiting approval…", ...SLACK_DEFAULT_LOADING_MESSAGES],
-          });
-        }
-        log.info("approval card posted", {
-          call_id: event.data.callId,
-          tool: event.data.toolName,
-          message_ts: posted.ts,
-        });
-      } catch (error) {
-        log.warn("approval card post failed", {
-          call_id: event.data.callId,
-          error: error instanceof Error ? error.message : String(error),
-        });
-      }
-    },
-
-    async "action.approval_resolved"(event, channel) {
-      const log = getLog();
-      const state = channel.state;
-      const messageTs = state.approvalMessageByCallId?.[event.data.callId];
-      if (state.channelId !== null && messageTs !== undefined && messageTs !== "") {
-        const blocks = buildResolvedApprovalBlocks({
-          toolName: event.data.toolName,
-          decision: event.data.decision,
-          ...(event.data.by === undefined ? {} : { byUserId: event.data.by }),
-        });
-        const verb = event.data.decision === "approve" ? "Approved" : "Denied";
-        await updateMessage({
-          botToken,
-          channel: state.channelId,
-          ts: messageTs,
-          text: `${verb} — ${event.data.toolName}`,
-          blocks,
-        });
-        const next = { ...(state.approvalMessageByCallId ?? {}) };
-        delete next[event.data.callId];
-        channel.state.approvalMessageByCallId = next;
-      }
-      await resolveChip(state);
-      log.info("approval resolved in slack", {
-        call_id: event.data.callId,
-        decision: event.data.decision,
-      });
-    },
-
-    async "action.auth_requested"(event, channel, ctx) {
-      const log = getLog();
-      const state = channel.state;
-      if (state.channelId === null || state.threadTs === null) {
-        return;
-      }
-      const blocks = buildAuthBlocks({
-        sessionId: ctx.session.id,
-        callId: event.data.callId,
-        toolName: event.data.toolName,
-        connection: event.data.connection,
-        authUrl: event.data.authUrl,
-      });
-      try {
-        const posted = await postMessage({
-          botToken,
-          channel: state.channelId,
-          threadTs: state.threadTs,
-          text: `Authorization required for \`${event.data.connection}\``,
-          blocks,
-        });
-        channel.state.approvalMessageByCallId = {
-          ...(state.approvalMessageByCallId ?? {}),
-          [event.data.callId]: posted.ts,
-        };
-        if (status) {
-          await setThreadStatus({
-            botToken,
-            channelId: state.channelId,
-            threadTs: state.threadTs,
-            status: authThreadStatus(event.data.connection),
-            loadingMessages: [
-              authThreadStatus(event.data.connection),
-              ...SLACK_DEFAULT_LOADING_MESSAGES,
-            ],
-          });
-        }
-        log.info("auth card posted", {
-          call_id: event.data.callId,
-          connection: event.data.connection,
-          message_ts: posted.ts,
-        });
-      } catch (error) {
-        log.warn("auth card post failed", {
-          call_id: event.data.callId,
-          error: error instanceof Error ? error.message : String(error),
-        });
-      }
-    },
-
-    async "action.auth_resolved"(event, channel) {
-      const log = getLog();
-      const state = channel.state;
-      const messageTs = state.approvalMessageByCallId?.[event.data.callId];
-      if (state.channelId !== null && messageTs !== undefined && messageTs !== "") {
-        const blocks = buildResolvedAuthBlocks({
-          connection: event.data.connection,
-          decision: event.data.decision,
-          byUserId: event.data.by,
-        });
-        const verb = event.data.decision === "approve" ? "Connected" : "Cancelled";
-        await updateMessage({
-          botToken,
-          channel: state.channelId,
-          ts: messageTs,
-          text: `${verb} — ${event.data.connection}`,
-          blocks,
-        });
-        const next = { ...(state.approvalMessageByCallId ?? {}) };
-        delete next[event.data.callId];
-        channel.state.approvalMessageByCallId = next;
-      }
-      await resolveChip(state);
-      log.info("auth resolved in slack", {
-        call_id: event.data.callId,
-        decision: event.data.decision,
-      });
-    },
-  };
-}