@cursor/bdk 0.2.2 → 0.2.4

package/src/channels/slack/defaults.ts

@@ -1,714 +0,0 @@
-/**
- * Default inbound handlers and stream-event sinks for the Slack channel.
- */
-
-import {
-  markHostedFirstVisibleReply,
-  noteHostedVisibleReplyError,
-} from "../../internal/hosted-execution-latency.js";
-import type { ChannelEventContext, ChannelEventHandlers, HostContext } from "../../types.js";
-import { buildAgenticEvents } from "./agentic-delivery.js";
-import { postMessage, setThreadStatus } from "./api.js";
-import { maybeSetSuggestedPrompts } from "./assistant.js";
-import { defaultSlackAuth } from "./auth.js";
-import { SLACK_DEFAULT_LOADING_MESSAGES } from "./constants.js";
-import { paintSlackFooter, turnDurationMs } from "./footer.js";
-import { createStreamDeliveryStrategy } from "./live-delivery.js";
-import { defaultSlackLog, type SlackLog } from "./log.js";
-import { createProgressDelivery } from "./progress-delivery.js";
-import { createReasoningCard, type ReasoningCard } from "./reasoning-card.js";
-import { commitReasoningChip, nextReasoningChip } from "./reasoning-chip.js";
-import { redactSecretTokens } from "./redact.js";
-import { resolveSlackReply } from "./reply-options.js";
-import type { StreamTaskChunk } from "./stream.js";
-import { createToolCards, type ToolCards } from "./tool-cards.js";
-import { rememberPendingToolCall, takeToolChipLine } from "./tool-chip.js";
-import type {
-  SlackAccessPolicy,
-  SlackChannelState,
-  SlackCredentials,
-  SlackMessageHandler,
-  SlackReplyOptions,
-  SlackRespondTo,
-  SlackSuggestedPrompt,
-  SlackToolLabels,
-} from "./types.js";
-
-const SLACK_TURN_FAILURE_FALLBACK =
-  "I hit an error while handling your request. Please try again or rephrase.";
-const SLACK_TURN_FAILURE_MAX_CHARS = 400;
-
-export function resolveSlackRespondTo(policy: SlackAccessPolicy | undefined): SlackRespondTo {
-  return policy?.respondTo === "author" ? "author" : "thread";
-}
-
-/** Defaults to true when omitted. */
-export function resolveSlackBlockExternals(policy: SlackAccessPolicy | undefined): boolean {
-  return policy?.blockExternals !== false;
-}
-
-/** Scrubbed turn.failed body for Slack (secrets / paths / URLs stripped). */
-export function formatSlackTurnFailureMessage(raw: string | undefined): string {
-  const scrubbed = scrubSlackErrorDetail(raw?.trim() ?? "");
-  if (scrubbed === "") {
-    return SLACK_TURN_FAILURE_FALLBACK;
-  }
-  if (/^I hit an error/i.test(scrubbed)) {
-    return scrubbed;
-  }
-  return `I hit an error while handling your request: ${scrubbed}`;
-}
-
-function streamHasCards(state: SlackChannelState): boolean {
-  if (state.reasoningCard !== undefined) {
-    return true;
-  }
-  const counts = state.toolCardCounts;
-  return counts !== undefined && Object.keys(counts).length > 0;
-}
-
-function scrubSlackErrorDetail(message: string): string {
-  const scrubbed = redactSecretTokens(message)
-    .replace(/https?:\/\/\S+/gi, "[url]")
-    .replace(/\/(?:home|Users|var\/folders)\/\S+/g, "[path]")
-    .replace(/\b[A-Za-z]:(?:\\|\/)[^\s]+/g, "[path]")
-    .replace(/\\\\[^\s]+/g, "[path]")
-    .replace(/\s+/g, " ")
-    .trim();
-  if (scrubbed.length <= SLACK_TURN_FAILURE_MAX_CHARS) {
-    return scrubbed;
-  }
-  return `${scrubbed.slice(0, SLACK_TURN_FAILURE_MAX_CHARS - 1)}…`;
-}
-
-function resolveLoadingMessages(loadingMessages: readonly string[] | undefined): string[] {
-  if (loadingMessages !== undefined && loadingMessages.length > 0) {
-    return [...loadingMessages];
-  }
-  return [...SLACK_DEFAULT_LOADING_MESSAGES];
-}
-
-/** Default mention/DM inbound handler (optional custom loading rotation). */
-export function createDefaultOnInbound(
-  loadingMessages?: readonly string[],
-  policy?: SlackAccessPolicy,
-): SlackMessageHandler {
-  const rotating = resolveLoadingMessages(loadingMessages);
-  const respondTo = resolveSlackRespondTo(policy);
-  return async (ctx, message) => {
-    await ctx.thread.startTyping("Thinking…", rotating);
-    const auth = defaultSlackAuth(message, ctx, { respondTo });
-    return auth === null ? null : { auth };
-  };
-}
-
-/**
- * Default watched-channel-post handler (optional custom loading rotation).
- * Same principal policy as mentions, tagged with
- * `engagement: "channel_post"` for auth policies.
- */
-export function createDefaultOnChannelPost(
-  loadingMessages?: readonly string[],
-  policy?: SlackAccessPolicy,
-): SlackMessageHandler {
-  const rotating = resolveLoadingMessages(loadingMessages);
-  const respondTo = resolveSlackRespondTo(policy);
-  return async (ctx, message) => {
-    await ctx.thread.startTyping("Thinking…", rotating);
-    const auth = defaultSlackAuth(message, ctx, {
-      engagement: "channel_post",
-      respondTo,
-    });
-    return auth === null ? null : { auth };
-  };
-}
-
-export const defaultOnAppMention: SlackMessageHandler = createDefaultOnInbound();
-export const defaultOnDirectMessage: SlackMessageHandler = createDefaultOnInbound();
-export const defaultOnChannelPost: SlackMessageHandler = createDefaultOnChannelPost();
-
-export interface BuildDefaultEventsOptions {
-  credentials?: SlackCredentials;
-  /** Same shape as `slackChannel({ reply })`; see {@link SlackReplyOptions}. */
-  reply?: SlackReplyOptions;
-  /** Same as `slackChannel({ toolLabels })`. */
-  toolLabels?: SlackToolLabels;
-  /** @deprecated Use `reply`. */
-  streaming?: boolean;
-  /** @deprecated Use `reply`. */
-  thinkingSteps?: boolean;
-  /** @deprecated Use `reply.status.idle`. */
-  loadingMessages?: readonly string[];
-  suggestedPrompts?: SlackSuggestedPrompt[];
-  suggestedPromptsTitle?: string;
-  /** Resolved per-call so channel onStart can rebind the server logger. */
-  getLog?: () => SlackLog;
-}
-
-/**
- * Build default stream-event handlers (typing, streaming, replies).
- *
- * `reply.mode: "agentic"` installs the communication-tool watcher
- * instead of the post/stream sinks.
- *
- * Tool-approval cards are a separate primitive — compose with
- * `buildToolApprovalEvents` or set `toolApprovals: true` on `slackChannel`.
- */
-export function buildDefaultEvents(
-  options: BuildDefaultEventsOptions = {},
-): ChannelEventHandlers<SlackChannelState> {
-  const credentials = options.credentials;
-  const reply = resolveSlackReply({
-    reply: options.reply,
-    toolLabels: options.toolLabels,
-    streaming: options.streaming,
-    thinkingSteps: options.thinkingSteps,
-    loadingMessages: options.loadingMessages,
-  });
-  if (reply.mode === "agentic") {
-    return buildAgenticEvents({
-      credentials,
-      getLog: options.getLog,
-      ack: reply.ack,
-      placeholder: reply.placeholder,
-      status: reply.status,
-      footer: reply.footer,
-    });
-  }
-  const streaming = reply.mode === "stream";
-  const suggestedPrompts = options.suggestedPrompts ?? [];
-  const suggestedPromptsTitle = options.suggestedPromptsTitle;
-  const loadingMessages = reply.status.idle;
-  const botToken = credentials?.botToken;
-  const getLog = options.getLog ?? (() => defaultSlackLog);
-  const strategy = createStreamDeliveryStrategy({ botToken, getLog });
-  const progress = createProgressDelivery({ botToken, getLog });
-
-  const streamLive = (state: SlackChannelState): boolean =>
-    streaming && !state.streamingUnavailable;
-
-  const streamTarget = (channel: ChannelEventContext<SlackChannelState>): string | null => {
-    const channelId = channel.state.streamChannelId ?? channel.state.channelId;
-    if (channelId === null || channelId === "" || channel.state.threadTs === null) {
-      return null;
-    }
-    return channelId;
-  };
-
-  const sendCards = async (args: {
-    channel: ChannelEventContext<SlackChannelState>;
-    sessionId: string;
-    chunks: StreamTaskChunk[];
-  }): Promise<boolean> => {
-    if (!streamLive(args.channel.state)) {
-      return false;
-    }
-    const channelId = streamTarget(args.channel);
-    if (channelId === null) {
-      return false;
-    }
-    return strategy.appendChunks({ ...args, channelId });
-  };
-
-  const reasoning: ReasoningCard | null =
-    reply.reasoningCard === false
-      ? null
-      : createReasoningCard(reply.reasoningCard, ({ chunk, ...rest }) =>
-          sendCards({ ...rest, chunks: [chunk] }),
-        );
-  const toolCards: ToolCards | null =
-    reply.toolCards === false ? null : createToolCards(reply.toolCards, reply.toolLabel);
-
-  const completeReasoning = async (
-    channel: ChannelEventContext<SlackChannelState>,
-    sessionId: string,
-  ): Promise<void> => {
-    if (reasoning?.inProgress(channel)) {
-      await reasoning.flush({ channel, sessionId, status: "complete" });
-    }
-  };
-
-  /** Subagent events carry `parentCallId`; cards and the reply are the parent's. */
-  const nested = (event: { data: { parentCallId?: string } }): boolean =>
-    event.data.parentCallId !== undefined;
-
-  const clearWorkingStatus = async (channelId: string, threadTs: string): Promise<void> => {
-    const result = await setThreadStatus({
-      botToken,
-      channelId,
-      threadTs,
-      status: "",
-    });
-    if (!result.ok) {
-      getLog().warn("slack setStatus not-ok", {
-        error: result.error,
-        channel: channelId,
-        thread_ts: threadTs,
-      });
-    }
-  };
-
-  const finishProgress = async (args: {
-    channel: ChannelEventContext<SlackChannelState>;
-    text: string;
-    sessionId: string;
-  }): Promise<boolean> => {
-    const log = getLog();
-    const state = args.channel.state;
-    if (state.channelId === null || state.threadTs === null || args.text === "") {
-      return false;
-    }
-    if (await progress.replace({ channel: args.channel, text: args.text })) {
-      log.info("reply delivered via progress update", {
-        channel: state.channelId,
-        thread_ts: state.threadTs,
-        session: args.sessionId,
-        chars: args.text.length,
-      });
-      markHostedFirstVisibleReply({
-        outcome: "progress_update",
-        deliverySurface: "slack",
-      });
-      return true;
-    }
-    await progress.clear({ channel: args.channel });
-    try {
-      const posted = await postMessage({
-        botToken,
-        channel: state.channelId,
-        text: args.text,
-        threadTs: state.threadTs,
-      });
-      state.lastPostedText = args.text;
-      state.lastBotMessageTs = posted.ts;
-      log.info("reply delivered via postMessage", {
-        channel: state.channelId,
-        thread_ts: state.threadTs,
-        message_ts: posted.ts,
-        session: args.sessionId,
-        chars: args.text.length,
-      });
-      markHostedFirstVisibleReply({
-        outcome: "final_post",
-        deliverySurface: "slack",
-      });
-      return true;
-    } catch (error) {
-      log.error(`postMessage failed: ${error instanceof Error ? error.message : String(error)}`, {
-        channel: state.channelId,
-        thread_ts: state.threadTs,
-        session: args.sessionId,
-      });
-      noteHostedVisibleReplyError({ deliverySurface: "slack" });
-      return false;
-    }
-  };
-
-  /**
-   * Deliver assistant text to the bound Slack thread. Used by a stop-reason
-   * `message.completed` and by `turn.completed` when the last assistant
-   * block was `finishReason: "tool_call"` (answer then `tag_artifact`,
-   * etc.) so the playground result still reaches Slack.
-   */
-  const deliverReplyText = async (args: {
-    channel: ChannelEventContext<SlackChannelState>;
-    text: string;
-    sessionId: string;
-  }): Promise<boolean> => {
-    const state = args.channel.state;
-    if (state.channelId === null || state.threadTs === null || args.text === "") {
-      return false;
-    }
-    if (state.lastPostedText === args.text) {
-      // Stream append sets this watermark while chat.stopStream is still
-      // pending. Treat a match as "already on Slack", not "already finalized".
-      const streamTs = state.streamTs;
-      if (streamTs !== null && streamTs !== "") {
-        if (streamLive(state)) {
-          await strategy.finalize({
-            channel: args.channel,
-            channelId: state.streamChannelId ?? state.channelId,
-            text: args.text,
-            sessionId: args.sessionId,
-          });
-        } else {
-          await strategy.cleanupOrphan({ channel: args.channel });
-        }
-      }
-      return true;
-    }
-
-    if (streamLive(state)) {
-      const { delivered } = await strategy.finalize({
-        channel: args.channel,
-        channelId: state.streamChannelId ?? state.channelId,
-        text: args.text,
-        sessionId: args.sessionId,
-      });
-      if (delivered) {
-        return true;
-      }
-    }
-
-    return finishProgress(args);
-  };
-
-  const paintReplyFooter = async (args: {
-    channel: ChannelEventContext<SlackChannelState>;
-    sessionId: string;
-    status: "completed" | "failed";
-    host?: HostContext;
-  }): Promise<void> => {
-    const state = args.channel.state;
-    const ts = state.lastBotMessageTs;
-    const text = state.lastPostedText;
-    if (
-      ts == null ||
-      ts === "" ||
-      text == null ||
-      text === "" ||
-      state.channelId === null ||
-      state.threadTs === null ||
-      streamHasCards(state)
-    ) {
-      return;
-    }
-    const result = await paintSlackFooter({
-      footer: reply.footer,
-      ctx: {
-        sessionId: args.sessionId,
-        channelId: state.channelId,
-        threadTs: state.threadTs,
-        text,
-        status: args.status,
-        durationMs: turnDurationMs(state.turnStartedAtMs),
-        host: args.host,
-      },
-      ts,
-      botToken,
-    });
-    if (result !== undefined && !result.ok) {
-      getLog().warn(`reply footer failed: ${result.error}`, {
-        channel: state.channelId,
-        ts,
-      });
-    }
-  };
-
-  return {
-    async "turn.started"(event, channel) {
-      const log = getLog();
-      await progress.clear({ channel });
-      channel.state.pendingToolCallMessage = null;
-      channel.state.lastReasoningTypingAtMs = null;
-      channel.state.lastReasoningTypingStatus = null;
-      channel.state.streamTs = null;
-      channel.state.streamChannelId = null;
-      channel.state.streamFull = false;
-      // A stream failure downgrades the rest of its own turn, not the thread.
-      channel.state.streamingUnavailable = false;
-      channel.state.streamAppendedChunks = 0;
-      channel.state.lastPostedText = null;
-      channel.state.streamBlockText = null;
-      channel.state.turnStartedAtMs = Date.now();
-      channel.state.reasoningCard = undefined;
-      channel.state.toolCardCounts = {};
-      // Keep lastBotMessageTs across turns — warm delta watermark.
-      channel.state.approvalMessageByCallId = {};
-
-      const state = channel.state;
-      if (state.channelId === null || state.threadTs === null) {
-        return;
-      }
-
-      log.info("turn.started", {
-        session: event.sessionId,
-        turn: event.turnId,
-        channel: state.channelId,
-        thread_ts: state.threadTs,
-      });
-
-      await setThreadStatus({
-        botToken,
-        channelId: state.channelId,
-        threadTs: state.threadTs,
-        status: "Working…",
-        loadingMessages,
-      });
-    },
-
-    async "message.appended"(event, channel) {
-      // Nested (subagent) text is not the reply.
-      if (nested(event) || !streamLive(channel.state)) {
-        return;
-      }
-      const channelId = streamTarget(channel);
-      if (channelId === null) {
-        return;
-      }
-
-      await completeReasoning(channel, event.sessionId);
-      await strategy.append({
-        channel,
-        channelId,
-        text: event.data.text,
-        sessionId: event.sessionId,
-      });
-    },
-
-    async "reasoning.appended"(event, channel) {
-      if (!nested(event)) {
-        await reasoning?.append({
-          channel,
-          sessionId: event.sessionId,
-          text: event.data.text,
-        });
-      }
-
-      // The chip is hidden while a stream is open.
-      if (!reply.status.reasoning || channel.state.streamTs !== null) {
-        return;
-      }
-      const now = Date.now();
-      const status = nextReasoningChip(channel.state, event.data.text, now);
-      if (status === undefined) {
-        return;
-      }
-      if (channel.state.channelId === null || channel.state.threadTs === null) {
-        return;
-      }
-      // One entry: Slack cycles `loading_messages` every couple of seconds,
-      // so padding an informative line with the rotation makes the chip
-      // flip between the reasoning and filler until the next update.
-      const painted = await setThreadStatus({
-        botToken,
-        channelId: channel.state.channelId,
-        threadTs: channel.state.threadTs,
-        status,
-        loadingMessages: [status],
-      });
-      if (painted.ok) {
-        commitReasoningChip(channel.state, status, now);
-      }
-    },
-
-    async "reasoning.completed"(event, channel) {
-      if (reasoning === null || nested(event)) {
-        return;
-      }
-      reasoning.endBlock(channel);
-      await reasoning.flush({
-        channel,
-        sessionId: event.sessionId,
-        status: "in_progress",
-      });
-    },
-
-    async "actions.requested"(event, channel) {
-      const calls = event.data.calls;
-      const statusText = takeToolChipLine(channel.state, reply.status.tools, calls);
-
-      if (toolCards !== null && strategy.inlineToolSteps && !nested(event)) {
-        // Card order: the thinking that led to these tools goes first.
-        await reasoning?.flush({
-          channel,
-          sessionId: event.sessionId,
-          status: "in_progress",
-        });
-        const streamed = await sendCards({
-          channel,
-          sessionId: event.sessionId,
-          chunks: toolCards.forCalls(channel.state, calls),
-        });
-        // An open stream hides the chip; skip the status write.
-        if (streamed) {
-          return;
-        }
-      }
-
-      if (statusText === undefined) {
-        return;
-      }
-      if (channel.state.channelId === null || channel.state.threadTs === null) {
-        return;
-      }
-      // Hold the tool line steady; see reasoning.appended.
-      await setThreadStatus({
-        botToken,
-        channelId: channel.state.channelId,
-        threadTs: channel.state.threadTs,
-        status: statusText,
-        loadingMessages: [statusText],
-      });
-      if (
-        toolCards !== null &&
-        channel.state.streamingUnavailable === true &&
-        (channel.state.streamTs === null || channel.state.streamTs === "")
-      ) {
-        await progress.upsert({ channel, text: statusText });
-      }
-    },
-
-    async "action.result"(event, channel) {
-      const streamTs = channel.state.streamTs;
-      if (
-        toolCards === null ||
-        !strategy.inlineToolSteps ||
-        nested(event) ||
-        streamTs === null ||
-        streamTs === ""
-      ) {
-        return;
-      }
-      await sendCards({
-        channel,
-        sessionId: event.sessionId,
-        chunks: [
-          toolCards.forResult(channel.state, {
-            callId: event.data.callId,
-            toolName: event.data.toolName,
-            output: event.data.output,
-            isError: event.data.isError,
-          }),
-        ],
-      });
-    },
-
-    async "message.completed"(event, channel) {
-      if (nested(event)) {
-        return;
-      }
-      rememberPendingToolCall(channel.state, event.data.finishReason, event.data.text);
-      if (event.data.finishReason === "tool_call") {
-        // The harness restarts its cumulative text after a tool call, so the
-        // next block appends in full instead of diffing against this one.
-        channel.state.streamBlockText = null;
-        return;
-      }
-
-      const state = channel.state;
-      if (state.channelId === null || state.threadTs === null) {
-        return;
-      }
-
-      await completeReasoning(channel, event.sessionId);
-
-      // Empty final text: still close any open stream / clear the skeleton
-      // and clear typing.
-      if (event.data.text === "") {
-        await strategy.finalizeEmpty({ channel });
-        await progress.clear({ channel });
-        await clearWorkingStatus(state.channelId, state.threadTs);
-        return;
-      }
-
-      await deliverReplyText({
-        channel,
-        text: event.data.text,
-        sessionId: event.sessionId,
-      });
-      await clearWorkingStatus(state.channelId, state.threadTs);
-    },
-
-    async "turn.completed"(event, channel, ctx) {
-      const log = getLog();
-      log.info("turn.completed", {
-        session: event.sessionId,
-        turn: event.turnId,
-        channel: channel.state.channelId,
-        thread_ts: channel.state.threadTs,
-      });
-
-      // Mid-turn `tool_call` text is held as status, not posted. If the
-      // turn ends without a later `finishReason: "stop"` block, the
-      // playground still has `result` (last assistant text) and Slack
-      // would otherwise stay silent.
-      const result = event.data.result;
-      const unpublished =
-        typeof result === "string" && result !== "" && result !== channel.state.lastPostedText;
-      await completeReasoning(channel, event.sessionId);
-      if (unpublished) {
-        await deliverReplyText({
-          channel,
-          text: result,
-          sessionId: event.sessionId,
-        });
-      }
-      // Always close leftovers. deliverReplyText may fall through to
-      // postMessage when streaming is unavailable and leave streamTs open.
-      await strategy.cleanupOrphan({ channel });
-      await progress.clear({ channel });
-      await paintReplyFooter({
-        channel,
-        sessionId: event.sessionId,
-        status: "completed",
-        host: ctx.host,
-      });
-
-      // Always drop the assistant chip. message.completed already clears
-      // after a normal reply, but a tool-call-only finish (or a missed
-      // final assistant message) never hits that path — leaving
-      // "Working…" stuck until Slack expires it.
-      if (channel.state.channelId !== null && channel.state.threadTs !== null) {
-        await clearWorkingStatus(channel.state.channelId, channel.state.threadTs);
-      }
-
-      if (
-        suggestedPrompts.length === 0 ||
-        channel.state.channelId === null ||
-        channel.state.threadTs === null
-      ) {
-        return;
-      }
-      await maybeSetSuggestedPrompts({
-        botToken,
-        channelId: channel.state.channelId,
-        threadTs: channel.state.threadTs,
-        prompts: suggestedPrompts,
-        ...(suggestedPromptsTitle === undefined ? {} : { title: suggestedPromptsTitle }),
-        log,
-      });
-    },
-
-    async "turn.failed"(event, channel, ctx) {
-      const log = getLog();
-      const state = channel.state;
-      log.error("turn.failed", {
-        session: event.sessionId,
-        turn: event.turnId,
-        error: event.data.message,
-        channel: state.channelId,
-        thread_ts: state.threadTs,
-      });
-      if (state.channelId === null || state.threadTs === null) {
-        return;
-      }
-      const errorText = formatSlackTurnFailureMessage(event.data.message);
-
-      let delivered = false;
-      if (streamLive(state)) {
-        await completeReasoning(channel, event.sessionId);
-        ({ delivered } = await strategy.fail({
-          channel,
-          channelId: state.streamChannelId ?? state.channelId,
-          errorText,
-          sessionId: event.sessionId,
-        }));
-      }
-      if (!delivered) {
-        await finishProgress({
-          channel,
-          text: errorText,
-          sessionId: event.sessionId,
-        });
-      }
-      await paintReplyFooter({
-        channel,
-        sessionId: event.sessionId,
-        status: "failed",
-        host: ctx.host,
-      });
-      await clearWorkingStatus(state.channelId, state.threadTs);
-    },
-  };
-}