@cursor/july 0.1.1

package/src/channels/slack/dispatch.ts

@@ -0,0 +1,293 @@
+/**
+ * Shared inbound dispatch for Slack Events API bodies and Socket Mode.
+ */
+
+import { SessionBusyError } from "../../internal/session-engine.js";
+import type { HostContext, JsonValue, SendMessageFn } from "../../types.js";
+import { buildSlackBinding, slackContinuationKey } from "./api.js";
+import { firstLineTitle, maybeSetThreadTitle } from "./assistant.js";
+import type { ChannelPostWatcher } from "./channel-watch.js";
+import type { EventIdDedupe } from "./event-id-dedupe.js";
+import {
+  formatSlackContextBlock,
+  parseAppMentionEvent,
+  parseChannelMessageEvent,
+  parseDirectMessageEvent,
+} from "./inbound.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import type {
+  SlackChannelState,
+  SlackCredentials,
+  SlackDispatchDecision,
+  SlackMessage,
+  SlackMessageHandler,
+} from "./types.js";
+
+const BUSY_REPLY =
+  "I'm still working on your previous message in this thread — I'll reply when that finishes. Send another message after that.";
+
+/** Blank per-session adapter state. */
+export function emptySlackChannelState(
+  patch: Partial<SlackChannelState> = {}
+): SlackChannelState {
+  return {
+    channelId: null,
+    threadTs: null,
+    teamId: null,
+    triggeringUserId: null,
+    pendingToolCallMessage: null,
+    lastReasoningTypingAtMs: null,
+    lastReasoningTypingStatus: null,
+    streamTs: null,
+    streamChannelId: null,
+    lastPostedText: null,
+    streamingUnavailable: false,
+    approvalMessageByCallId: {},
+    ...patch,
+  };
+}
+
+export interface SlackInboundDispatchDeps {
+  send: SendMessageFn;
+  waitUntil: (promise: Promise<unknown>) => void;
+  onAppMention: SlackMessageHandler;
+  onDirectMessage: SlackMessageHandler;
+  credentials: SlackCredentials | undefined;
+  eventIds: EventIdDedupe;
+  host: HostContext;
+  log?: SlackLog;
+  /** Dispatch on `app_mention`. Defaults to `true`. */
+  mentionsEnabled?: boolean;
+  /** Dispatch on direct messages. Defaults to `true`. */
+  directMessagesEnabled?: boolean;
+  /** Opt-in channel watch; absent = channel posts are ignored. */
+  channelWatch?: ChannelPostWatcher;
+}
+
+export async function dispatchInboundMessage(args: {
+  kind: "app_mention" | "direct_message" | "channel_post";
+  message: SlackMessage;
+  handler: SlackMessageHandler;
+  send: SendMessageFn;
+  credentials: SlackCredentials | undefined;
+  host: HostContext;
+  log?: SlackLog;
+  eventId?: string;
+}): Promise<void> {
+  const { message, kind } = args;
+  const log = args.log ?? defaultSlackLog;
+  const binding = buildSlackBinding({
+    botToken: args.credentials?.botToken,
+    channelId: message.channelId,
+    threadTs: message.threadTs,
+    host: args.host,
+    log,
+    ...(message.teamId === undefined ? {} : { teamId: message.teamId }),
+  });
+
+  log.info("inbound", {
+    kind,
+    event_id: args.eventId,
+    channel: message.channelId,
+    thread_ts: message.threadTs,
+    message_ts: message.ts,
+    user: message.author?.userId,
+    team: message.teamId,
+  });
+
+  if (message.ts === message.threadTs) {
+    await maybeSetThreadTitle({
+      botToken: args.credentials?.botToken,
+      channelId: message.channelId,
+      threadTs: message.threadTs,
+      title: firstLineTitle(message.markdown),
+      log,
+    });
+  }
+
+  let decision: SlackDispatchDecision | null | undefined;
+  try {
+    decision = await args.handler(binding, message);
+  } catch (error) {
+    log.error(`${kind} handler failed`, {
+      error: error instanceof Error ? error.message : String(error),
+      channel: message.channelId,
+      thread_ts: message.threadTs,
+      event_id: args.eventId,
+    });
+    return;
+  }
+  if (decision === null || decision === undefined) {
+    log.info("inbound skipped (handler returned null)", {
+      kind,
+      channel: message.channelId,
+      thread_ts: message.threadTs,
+      event_id: args.eventId,
+    });
+    return;
+  }
+
+  const userText = decision.message ?? message.markdown;
+  const prompt = [
+    formatSlackContextBlock({
+      userId: message.author?.userId ?? "",
+      channelId: message.channelId,
+      threadTs: message.threadTs,
+      ...(message.author?.userName === undefined
+        ? {}
+        : { userName: message.author.userName }),
+      ...(message.teamId === undefined ? {} : { teamId: message.teamId }),
+    }),
+    ...(decision.context ?? []),
+    "",
+    userText,
+  ]
+    .filter((part) => part.length > 0)
+    .join("\n");
+
+  const continuation = slackContinuationKey(
+    message.channelId,
+    message.threadTs
+  );
+
+  try {
+    const session = await args.send(prompt, {
+      auth: decision.auth,
+      continuationToken: continuation,
+      state: emptySlackChannelState({
+        channelId: message.channelId,
+        threadTs: message.threadTs,
+        teamId: message.teamId ?? null,
+        triggeringUserId: message.author?.userId ?? null,
+      }) as unknown as JsonValue,
+      title: decision.title ?? `slack:${message.channelId}:${message.threadTs}`,
+      workspaceDir: decision.workspaceDir,
+      workspaceFiles: decision.workspaceFiles,
+      cloud: decision.cloud,
+      sdkAgentId: decision.sdkAgentId,
+    });
+    log.info("session start", {
+      kind,
+      session: session.id,
+      is_new: session.isNew,
+      continuation,
+      channel: message.channelId,
+      thread_ts: message.threadTs,
+      event_id: args.eventId,
+    });
+  } catch (error) {
+    if (error instanceof SessionBusyError) {
+      log.info("session busy; notifying thread", {
+        kind,
+        channel: message.channelId,
+        thread_ts: message.threadTs,
+        continuation,
+        event_id: args.eventId,
+      });
+      try {
+        await binding.thread.post(BUSY_REPLY);
+      } catch (postError) {
+        log.error(
+          `busy reply failed: ${
+            postError instanceof Error ? postError.message : String(postError)
+          }`,
+          {
+            channel: message.channelId,
+            thread_ts: message.threadTs,
+            event_id: args.eventId,
+          }
+        );
+      }
+      return;
+    }
+    log.error(
+      `${kind} delivery failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      {
+        channel: message.channelId,
+        thread_ts: message.threadTs,
+        continuation,
+        event_id: args.eventId,
+      }
+    );
+  }
+}
+
+/**
+ * Parse an Events API body (or Socket Mode `events_api` payload) and dispatch
+ * app_mention / DM handlers. Deduplicates by `event_id` when present. Returns
+ * true when a handler was scheduled.
+ */
+export function dispatchInboundFromEventBody(
+  body: unknown,
+  deps: SlackInboundDispatchDeps
+): boolean {
+  const log = deps.log ?? defaultSlackLog;
+  let eventId: string | undefined;
+
+  if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+    const root = body as { event_id?: unknown };
+    if (typeof root.event_id === "string" && root.event_id.length > 0) {
+      eventId = root.event_id;
+      if (!deps.eventIds.tryHandle(root.event_id)) {
+        log.debug("inbound dedupe drop", { event_id: eventId });
+        return false;
+      }
+    }
+  }
+
+  const mention = parseAppMentionEvent(body);
+  if (mention !== null) {
+    if (deps.mentionsEnabled === false) {
+      log.debug("inbound ignored (mentions disabled)", { event_id: eventId });
+      return false;
+    }
+    deps.waitUntil(
+      dispatchInboundMessage({
+        kind: "app_mention",
+        message: mention,
+        handler: deps.onAppMention,
+        send: deps.send,
+        credentials: deps.credentials,
+        host: deps.host,
+        log,
+        ...(eventId === undefined ? {} : { eventId }),
+      })
+    );
+    return true;
+  }
+
+  const dm = parseDirectMessageEvent(body);
+  if (dm !== null) {
+    if (deps.directMessagesEnabled === false) {
+      log.debug("inbound ignored (direct messages disabled)", {
+        event_id: eventId,
+      });
+      return false;
+    }
+    deps.waitUntil(
+      dispatchInboundMessage({
+        kind: "direct_message",
+        message: dm,
+        handler: deps.onDirectMessage,
+        send: deps.send,
+        credentials: deps.credentials,
+        host: deps.host,
+        log,
+        ...(eventId === undefined ? {} : { eventId }),
+      })
+    );
+    return true;
+  }
+
+  if (deps.channelWatch !== undefined) {
+    const channelEvent = parseChannelMessageEvent(body);
+    if (channelEvent !== null) {
+      return deps.channelWatch.handle(channelEvent, eventId);
+    }
+  }
+
+  log.debug("inbound ignored (unhandled event shape)", { event_id: eventId });
+  return false;
+}

package/src/channels/slack/doctor.ts

@@ -0,0 +1,135 @@
+/**
+ * Slack channel doctor — verify env, Socket Mode app token, auth.test.
+ */
+
+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 };
+}
+
+export interface SlackDoctorOptions {
+  credentials?: SlackCredentials;
+  /** Per-agent env prefix (e.g. `MY_AGENT`). */
+  envPrefix?: string;
+}
+
+export async function runSlackDoctor(
+  options: SlackDoctorOptions = {}
+): Promise<SlackDoctorResult> {
+  const credentials =
+    options.credentials ?? credentialsFromEnv(options.envPrefix);
+  const envKeys = slackEnvKeys(options.envPrefix);
+  const checks: SlackDoctorCheck[] = [];
+
+  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 fetch(
+        "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`,
+  });
+
+  if (hasToken) {
+    try {
+      const auth = await callSlackApi({
+        botToken,
+        operation: "auth.test",
+        body: {},
+      });
+      if (auth.ok === true) {
+        checks.push({
+          id: "auth_test",
+          ok: true,
+          message: `auth.test ok (team=${String(auth.team ?? "?")}, 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)
+        }`,
+      });
+    }
+  }
+
+  return { ok: checks.every((check) => check.ok), checks, envKeys };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * 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;
+    },
+  };
+}

package/src/channels/slack/inbound.ts

@@ -0,0 +1,219 @@
+/**
+ * Parse Slack Events API payloads into structured inbound messages.
+ */
+
+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;
+}
+
+/** 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);
+  if (userId === undefined || userId === "") {
+    return undefined;
+  }
+  const botId = asString(event.bot_id);
+  const userName = asString(event.username);
+  return {
+    userId,
+    ...(userName === undefined ? {} : { userName }),
+    isBot: botId !== undefined && botId.length > 0,
+  };
+}
+
+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) ?? "";
+  const threadTs = asString(event.thread_ts) ?? ts;
+  const author = parseAuthor(event);
+  return {
+    text,
+    markdown: slackTextToMarkdown(text),
+    ts,
+    threadTs,
+    channelId,
+    ...(teamId === undefined ? {} : { teamId }),
+    ...(author === undefined ? {} : { author }),
+  };
+}
+
+export function parseAppMentionEvent(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 !== "app_mention") {
+    return null;
+  }
+  // Drop bot-authored mentions (mirrors DM filtering) to avoid loops.
+  const botId = asString(event.bot_id);
+  if (botId !== undefined && botId.length > 0) {
+    return null;
+  }
+  return buildSlackMessage(event, asString(root.team_id));
+}
+
+/**
+ * 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));
+}
+
+/** 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 };
+
+/**
+ * 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); edits and deletions are surfaced so a debounce window can
+ * update or cancel a pending dispatch.
+ */
+export function parseChannelMessageEvent(
+  body: unknown
+): 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) ?? "";
+
+  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 (botId !== undefined && botId.length > 0) {
+      return null;
+    }
+    const message = buildSlackMessage(
+      { ...nested, channel: channelId },
+      teamId
+    );
+    return message === null ? null : { kind: "edited", message };
+  }
+
+  if (subtype !== "" && subtype !== "file_share") {
+    return null;
+  }
+  const botId = asString(event.bot_id);
+  if (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");
+}