@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/slack/doctor.ts

@@ -1,338 +0,0 @@
-/**
- * Slack channel doctor — verify env, Socket Mode app token, auth.test, and
- * (when watched channels are supplied) that the bot token's workspace can
- * actually see, join, and read those channels.
- */
-
-import { callSlackApi, resolveAppToken, resolveBotToken } from "./api.js";
-import { credentialsFromEnv, slackEnvKeys } from "./credentials.js";
-import type { SlackCredentials } from "./types.js";
-
-export interface SlackDoctorCheck {
-  id: string;
-  ok: boolean;
-  message: string;
-}
-
-export interface SlackDoctorResult {
-  ok: boolean;
-  checks: SlackDoctorCheck[];
-  envKeys: { bot: string; app: string };
-  /**
-   * Things a bot token cannot prove. Event subscriptions are app-level
-   * config, so a fully green doctor can still be a silent agent.
-   */
-  notes?: string[];
-}
-
-export interface SlackDoctorOptions {
-  credentials?: SlackCredentials;
-  /** Per-agent env prefix (e.g. `MY_AGENT`). */
-  envPrefix?: string;
-  /**
-   * Watched channel ids (`engagement.channelPosts.allow`). Each is checked
-   * for visibility, bot membership, and history scope.
-   */
-  channels?: readonly string[];
-  /** Test seams. */
-  callImpl?: typeof callSlackApi;
-  fetchImpl?: typeof fetch;
-}
-
-/**
- * Socket Mode only delivers bot events the app subscribes to. Missing
- * subscriptions produce total silence with valid tokens, and cannot be read
- * back from a bot token.
- */
-const REQUIRED_BOT_EVENTS: Readonly<Record<string, string>> = {
-  app_mention: "@mentions of the bot",
-  "message.im": "direct messages",
-  "message.channels": "public channel posts",
-  "message.groups": "private channel posts",
-  reaction_added: "reaction handlers (onReactionAdded)",
-};
-
-function eventSubscriptionNote(): string {
-  const lines = Object.entries(REQUIRED_BOT_EVENTS).map(
-    ([event, purpose]) => `    ${event} — ${purpose}`,
-  );
-  return [
-    "A bot token cannot read Event Subscriptions. If every check above passes",
-    "but the bot is silent, verify these bot events are subscribed on the app",
-    "(Slack app config -> Event Subscriptions -> Subscribe to bot events):",
-    ...lines,
-  ].join("\n");
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return undefined;
-  }
-  return value as Record<string, unknown>;
-}
-
-function errorOf(response: Record<string, unknown>): string {
-  return typeof response.error === "string" ? response.error : "unknown";
-}
-
-/**
- * Visibility, membership, and history-scope checks for one watched channel.
- * `channel_not_found` here is the classic wrong-workspace bot token: the
- * token authenticates fine, it just belongs to a different installation.
- */
-async function checkChannel(args: {
-  call: typeof callSlackApi;
-  botToken: string;
-  channelId: string;
-}): Promise<SlackDoctorCheck[]> {
-  const { call, botToken, channelId } = args;
-  const checks: SlackDoctorCheck[] = [];
-
-  let info: Record<string, unknown>;
-  try {
-    info = await call({
-      botToken,
-      operation: "conversations.info",
-      body: { channel: channelId },
-    });
-  } catch (error) {
-    checks.push({
-      id: `channel_visible:${channelId}`,
-      ok: false,
-      message: `conversations.info threw: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    });
-    return checks;
-  }
-
-  if (info.ok !== true) {
-    const error = errorOf(info);
-    checks.push({
-      id: `channel_visible:${channelId}`,
-      ok: false,
-      message:
-        error === "channel_not_found"
-          ? `${channelId} not found by this bot token — the token is probably installed on a different workspace, or the channel id is wrong`
-          : `conversations.info failed: ${error}`,
-    });
-    return checks;
-  }
-
-  const channel = asRecord(info.channel);
-  const name = typeof channel?.name === "string" ? channel.name : "?";
-  checks.push({
-    id: `channel_visible:${channelId}`,
-    ok: true,
-    message: `${channelId} visible (#${name})`,
-  });
-
-  const isMember = channel?.is_member === true;
-  checks.push({
-    id: `channel_member:${channelId}`,
-    ok: isMember,
-    message: isMember
-      ? `bot is a member of ${channelId}`
-      : `bot is NOT a member of ${channelId} — invite it to the channel`,
-  });
-
-  let history: Record<string, unknown>;
-  try {
-    history = await call({
-      botToken,
-      operation: "conversations.history",
-      body: { channel: channelId, limit: 1 },
-    });
-  } catch (error) {
-    checks.push({
-      id: `channel_history:${channelId}`,
-      ok: false,
-      message: `conversations.history threw: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    });
-    return checks;
-  }
-
-  if (history.ok === true) {
-    checks.push({
-      id: `channel_history:${channelId}`,
-      ok: true,
-      message: `conversations.history ok for ${channelId}`,
-    });
-    return checks;
-  }
-
-  const error = errorOf(history);
-  const needed = typeof history.needed === "string" ? history.needed : undefined;
-  checks.push({
-    id: `channel_history:${channelId}`,
-    ok: false,
-    message:
-      error === "missing_scope"
-        ? `conversations.history missing scope${needed === undefined ? "" : ` ${needed}`} — add it and reinstall the app`
-        : `conversations.history failed: ${error}`,
-  });
-  return checks;
-}
-
-export async function runSlackDoctor(options: SlackDoctorOptions = {}): Promise<SlackDoctorResult> {
-  const credentials = options.credentials ?? credentialsFromEnv(options.envPrefix);
-  const envKeys = slackEnvKeys(options.envPrefix);
-  const checks: SlackDoctorCheck[] = [];
-  const call = options.callImpl ?? callSlackApi;
-  const fetchImpl = options.fetchImpl ?? fetch;
-
-  let appTokenRaw: string | undefined;
-  try {
-    appTokenRaw = await resolveAppToken(credentials);
-  } catch {
-    appTokenRaw = undefined;
-  }
-  const hasApp = appTokenRaw !== undefined && appTokenRaw !== "";
-  checks.push({
-    id: "app_token",
-    ok: hasApp,
-    message: hasApp
-      ? `${envKeys.app} present`
-      : `${envKeys.app} is missing (xapp-… with connections:write)`,
-  });
-  if (hasApp && appTokenRaw !== undefined) {
-    try {
-      const response = await fetchImpl("https://slack.com/api/apps.connections.open", {
-        method: "POST",
-        headers: {
-          authorization: `Bearer ${appTokenRaw}`,
-          "content-type": "application/x-www-form-urlencoded",
-        },
-        body: "",
-      });
-      const data = (await response.json()) as {
-        ok?: boolean;
-        error?: string;
-      };
-      if (data.ok === true) {
-        checks.push({
-          id: "connections_open",
-          ok: true,
-          message: "apps.connections.open ok (Socket Mode reachable)",
-        });
-      } else {
-        checks.push({
-          id: "connections_open",
-          ok: false,
-          message: `apps.connections.open failed: ${String(data.error ?? "unknown")}`,
-        });
-      }
-    } catch (error) {
-      checks.push({
-        id: "connections_open",
-        ok: false,
-        message: `apps.connections.open threw: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      });
-    }
-  }
-
-  let botToken: string | undefined;
-  try {
-    botToken = await resolveBotToken(credentials);
-  } catch {
-    botToken = undefined;
-  }
-  const hasToken = botToken !== undefined && botToken !== "";
-  checks.push({
-    id: "bot_token",
-    ok: hasToken,
-    message: hasToken ? `${envKeys.bot} present` : `${envKeys.bot} is missing`,
-  });
-
-  let authOk = false;
-  let botUserId = "";
-  if (hasToken) {
-    try {
-      const auth = await call({
-        botToken,
-        operation: "auth.test",
-        body: {},
-      });
-      if (auth.ok === true) {
-        authOk = true;
-        botUserId = typeof auth.user_id === "string" ? auth.user_id : "";
-        checks.push({
-          id: "auth_test",
-          ok: true,
-          message:
-            `auth.test ok (team=${String(auth.team ?? "?")}` +
-            `, team_id=${String(auth.team_id ?? "?")}` +
-            `, user=${String(auth.user ?? "?")})`,
-        });
-      } else {
-        checks.push({
-          id: "auth_test",
-          ok: false,
-          message: `auth.test failed: ${String(auth.error ?? "unknown")}`,
-        });
-      }
-    } catch (error) {
-      checks.push({
-        id: "auth_test",
-        ok: false,
-        message: `auth.test threw: ${error instanceof Error ? error.message : String(error)}`,
-      });
-    }
-  }
-
-  // The external-sender policy (`blockExternals`, on by default) classifies a
-  // sender as external whenever `users.info` fails — so a token that cannot
-  // look up users silently drops EVERY inbound event while all other checks
-  // stay green. Probe with the bot's own user id from auth.test.
-  if (authOk && botToken !== undefined && botUserId !== "") {
-    let info: Record<string, unknown> | undefined;
-    let threw: string | undefined;
-    try {
-      info = await call({
-        botToken,
-        operation: "users.info",
-        body: { user: botUserId },
-      });
-    } catch (error) {
-      threw = error instanceof Error ? error.message : String(error);
-    }
-    if (info?.ok === true) {
-      checks.push({
-        id: "users_read",
-        ok: true,
-        message: "users.info ok (users:read granted; external-sender policy can classify senders)",
-      });
-    } else {
-      const error = threw ?? (info === undefined ? "unknown" : errorOf(info));
-      const hint =
-        error === "missing_scope"
-          ? "add the users:read scope and reinstall the app"
-          : error === "user_not_found"
-            ? "the token cannot see its own workspace's users — probably a token from a different installation"
-            : "fix the token";
-      checks.push({
-        id: "users_read",
-        ok: false,
-        message: `users.info failed: ${error} — ${hint}. The external-sender policy fails open to "external" on users.info errors, so every inbound event is silently dropped.`,
-      });
-    }
-  }
-
-  const channels = options.channels ?? [];
-  if (authOk && botToken !== undefined && channels.length > 0) {
-    for (const channelId of channels) {
-      checks.push(...(await checkChannel({ call, botToken, channelId })));
-    }
-  }
-
-  return {
-    ok: checks.every(check => check.ok),
-    checks,
-    envKeys,
-    notes: [eventSubscriptionNote()],
-  };
-}

package/src/channels/slack/eval-directive.ts

@@ -1,306 +0,0 @@
-/**
- * Built-in Slack `eval` directive — run playground evals from a mention/DM
- * without per-agent custom handlers (parity with CLI / playground runs).
- *
- * Examples (after stripping @mentions):
- *   eval
- *   eval triage/open-incidents smoke
- *   eval --tag oncall
- *   eval list
- *   eval status
- *   eval help
- */
-
-import type { EvalRunSnapshot, HostEvalsApi } from "../../evals.js";
-import { EvalRunConflictError, EvalRunEmptyError } from "../../internal/eval-run-store.js";
-import { sleep } from "../../internal/sleep.js";
-import { stripLeadingSlackMentions } from "./stop.js";
-import type { SlackBinding } from "./types.js";
-
-const EVAL_POLL_MS = 2_000;
-const TYPING_STATUS_MAX = 50;
-
-export type SlackEvalDirective =
-  | { kind: "help" }
-  | { kind: "list" }
-  | { kind: "status" }
-  | { kind: "cancel"; runId: string }
-  | { kind: "run"; filterIds?: string[]; tags?: string[] };
-
-/**
- * Normalize inbound Slack text for directive parsing: strip leading
- * `<@U…>` mentions and leading `@U…` markdown mentions.
- */
-export function normalizeSlackEvalDirectiveBody(text: string): string {
-  let body = stripLeadingSlackMentions(text);
-  while (/^@[A-Za-z0-9._-]+\s+/.test(body)) {
-    body = body.replace(/^@[A-Za-z0-9._-]+\s+/, "").trim();
-  }
-  return body;
-}
-
-/**
- * Parse a Slack eval directive. Returns null when the message is not an
- * eval command (falls through to the normal agent handler).
- */
-export function parseSlackEvalDirective(text: string): SlackEvalDirective | null {
-  const body = normalizeSlackEvalDirectiveBody(text);
-  if (body.length === 0) {
-    return null;
-  }
-  const tokens = body.split(/\s+/).filter(t => t.length > 0);
-  if (tokens.length === 0 || !/^eval$/i.test(tokens[0] ?? "")) {
-    return null;
-  }
-
-  const rest = tokens.slice(1);
-  if (rest.length === 0) {
-    return { kind: "run" };
-  }
-
-  const head = (rest[0] ?? "").toLowerCase();
-  if (rest.length === 1 && (head === "help" || head === "-h" || head === "--help")) {
-    return { kind: "help" };
-  }
-  if (rest.length === 1 && (head === "list" || head === "ls")) {
-    return { kind: "list" };
-  }
-  if (rest.length === 1 && head === "status") {
-    return { kind: "status" };
-  }
-  if (head === "cancel") {
-    const runId = rest[1];
-    if (rest.length !== 2 || runId === undefined || runId.length === 0) {
-      return { kind: "help" };
-    }
-    return { kind: "cancel", runId };
-  }
-
-  const filterIds: string[] = [];
-  const tags: string[] = [];
-  for (let i = 0; i < rest.length; i++) {
-    const tok = rest[i] ?? "";
-    if (tok === "--tag" || tok === "-t") {
-      const value = rest[i + 1];
-      if (value === undefined || value.length === 0) {
-        return { kind: "help" };
-      }
-      tags.push(value);
-      i += 1;
-      continue;
-    }
-    if (tok.startsWith("--tag=")) {
-      const value = tok.slice("--tag=".length);
-      if (value.length === 0) {
-        return { kind: "help" };
-      }
-      tags.push(value);
-      continue;
-    }
-    if (tok.startsWith("-t=") && tok.length > 3) {
-      tags.push(tok.slice(3));
-      continue;
-    }
-    if (tok.startsWith("-")) {
-      // Unknown flag — surface help rather than treating as an eval id.
-      return { kind: "help" };
-    }
-    filterIds.push(tok);
-  }
-
-  const run: SlackEvalDirective = { kind: "run" };
-  if (filterIds.length > 0) {
-    run.filterIds = filterIds;
-  }
-  if (tags.length > 0) {
-    run.tags = tags;
-  }
-  return run;
-}
-
-/** True when either raw Slack text or markdown form is an eval directive. */
-export function isSlackEvalDirective(text: string, markdown: string): boolean {
-  return parseSlackEvalDirective(text) !== null || parseSlackEvalDirective(markdown) !== null;
-}
-
-export function formatSlackEvalHelp(): string {
-  return [
-    "*Eval commands* (same batches as the playground / `agent-sdk eval --prod`):",
-    "• `eval` — run all evals",
-    "• `eval <id> [id…]` — run specific eval ids",
-    "• `eval --tag <tag>` — run evals with a tag (`-t` also works)",
-    "• `eval list` — list available evals",
-    "• `eval status` — show the active or latest eval run",
-    "• `eval cancel <evalId>` — cancel a running eval batch",
-    "• `eval help` — this message",
-  ].join("\n");
-}
-
-export function formatSlackEvalList(
-  evals: Array<{
-    id: string;
-    description?: string;
-    tags?: string[];
-  }>,
-): string {
-  if (evals.length === 0) {
-    return "No evals found under `evals/`.";
-  }
-  const lines = [`*${evals.length} eval(s):*`];
-  for (const item of evals) {
-    const tags =
-      item.tags === undefined || item.tags.length === 0 ? "" : ` _[${item.tags.join(", ")}]_`;
-    const desc =
-      item.description === undefined || item.description === "" ? "" : ` — ${item.description}`;
-    lines.push(`• \`${item.id}\`${tags}${desc}`);
-  }
-  return lines.join("\n");
-}
-
-export function formatSlackEvalRunSummary(run: EvalRunSnapshot): string {
-  const { summary } = run;
-  const statusLabel =
-    run.status === "completed" ? "completed" : run.status === "failed" ? "failed" : "running";
-  const lines = [
-    `*Eval run* \`${run.runId}\` — *${statusLabel}*`,
-    `• ${summary.passed} passed, ${summary.failed} failed, ${summary.total} total` +
-      (summary.done < summary.total ? ` (${summary.done}/${summary.total} done)` : ""),
-  ];
-  if (run.error !== undefined && run.error !== "") {
-    lines.push(`• error: ${run.error}`);
-  }
-  for (const c of run.cases) {
-    const mark =
-      c.status !== "done"
-        ? c.status === "running"
-          ? "RUN "
-          : "….  "
-        : c.ok === true
-          ? "PASS"
-          : "FAIL";
-    const dur = c.durationMs === undefined ? "" : ` (${(c.durationMs / 1000).toFixed(1)}s)`;
-    const err = c.ok === false && c.error !== undefined && c.error !== "" ? ` — ${c.error}` : "";
-    lines.push(`\`${mark}\` \`${c.id}\`${dur}${err}`);
-  }
-  return lines.join("\n");
-}
-
-function truncateTyping(status: string): string {
-  if (status.length <= TYPING_STATUS_MAX) {
-    return status;
-  }
-  return `${status.slice(0, TYPING_STATUS_MAX - 1)}…`;
-}
-
-async function safeTyping(binding: SlackBinding, status: string): Promise<void> {
-  try {
-    await binding.thread.startTyping(truncateTyping(status));
-  } catch {
-    // best-effort status
-  }
-}
-
-async function safePost(binding: SlackBinding, text: string): Promise<void> {
-  try {
-    await binding.thread.post(text);
-  } catch {
-    // best-effort reply
-  }
-}
-
-/**
- * Handle a parsed Slack eval directive against {@link HostEvalsApi}.
- * Posts results in-thread; does not start an agent turn.
- */
-export async function handleSlackEvalDirective(args: {
-  directive: SlackEvalDirective;
-  evals: HostEvalsApi;
-  binding: SlackBinding;
-  /** Override poll interval (tests). */
-  pollMs?: number;
-}): Promise<void> {
-  const { directive, evals, binding } = args;
-  const pollMs = args.pollMs ?? EVAL_POLL_MS;
-
-  if (directive.kind === "help") {
-    await safePost(binding, formatSlackEvalHelp());
-    return;
-  }
-
-  if (directive.kind === "list") {
-    const listed = await evals.list();
-    await safePost(binding, formatSlackEvalList(listed.evals));
-    return;
-  }
-
-  if (directive.kind === "status") {
-    const { runs, activeRunId } = await evals.listRunsWithActive();
-    const run = (activeRunId === undefined ? undefined : await evals.get(activeRunId)) ?? runs[0];
-    if (run === undefined) {
-      await safePost(binding, "No eval runs yet. Try `eval list` then `eval`.");
-      return;
-    }
-    await safePost(binding, formatSlackEvalRunSummary(run));
-    return;
-  }
-
-  if (directive.kind === "cancel") {
-    try {
-      const run = await evals.cancel(directive.runId);
-      await safePost(
-        binding,
-        `Cancelled Eval ID \`${run.runId}\`.\n${formatSlackEvalRunSummary(run)}`,
-      );
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      await safePost(binding, `Failed to cancel eval: ${message}`);
-    }
-    return;
-  }
-
-  await safeTyping(binding, "Starting evals…");
-  let run: EvalRunSnapshot;
-  try {
-    run = await evals.start({
-      filterIds: directive.filterIds,
-      tags: directive.tags,
-    });
-  } catch (error) {
-    if (error instanceof EvalRunConflictError) {
-      const active = await evals.get(error.activeRunId);
-      await safePost(
-        binding,
-        active === undefined
-          ? `An eval run is already in progress (\`${error.activeRunId}\`).`
-          : `An eval run is already in progress:\n${formatSlackEvalRunSummary(active)}`,
-      );
-      return;
-    }
-    if (error instanceof EvalRunEmptyError) {
-      await safePost(binding, "No matching evals. Try `eval list` or `eval help`.");
-      return;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    await safePost(binding, `Failed to start evals: ${message}`);
-    return;
-  }
-
-  await safePost(
-    binding,
-    `Started Eval ID \`${run.runId}\` (${run.summary.total} case(s)). Cancel with \`eval cancel ${run.runId}\`.`,
-  );
-
-  while (run.status === "running") {
-    await safeTyping(binding, `Evals ${run.summary.done}/${run.summary.total}…`);
-    await sleep(pollMs);
-    const next = await evals.get(run.runId);
-    if (next === undefined) {
-      await safePost(binding, `Eval run \`${run.runId}\` disappeared before completion.`);
-      return;
-    }
-    run = next;
-  }
-
-  await safePost(binding, formatSlackEvalRunSummary(run));
-  await safeTyping(binding, "Evals done.");
-}

package/src/channels/slack/event-id-dedupe.ts

@@ -1,30 +0,0 @@
-/**
- * FIFO-capped event_id dedupe for Slack Events API / Socket Mode.
- * One instance per channel mount — not process-global.
- */
-
-const DEFAULT_CAP = 2_000;
-
-export interface EventIdDedupe {
-  /** Returns true the first time an id is seen; false if already seen. */
-  tryHandle(eventId: string): boolean;
-}
-
-export function createEventIdDedupe(cap: number = DEFAULT_CAP): EventIdDedupe {
-  const handled = new Set<string>();
-  return {
-    tryHandle(eventId: string): boolean {
-      if (handled.has(eventId)) {
-        return false;
-      }
-      handled.add(eventId);
-      if (handled.size > cap) {
-        const first = handled.values().next().value;
-        if (first !== undefined) {
-          handled.delete(first);
-        }
-      }
-      return true;
-    },
-  };
-}