@cursor/july 0.1.7 → 0.1.9

package/src/channels/slack/stop.ts

@@ -0,0 +1,25 @@
+/**
+ * Whole-message Slack "stop" directive (Benny parity).
+ *
+ * A message whose body is only `@bot stop` / `stop` cancels the active turn.
+ * The word "stop" embedded in a longer message is not a directive.
+ */
+
+const MENTION_RE = /^<@[A-Z0-9]+>\s*/i;
+
+/** Strip leading Slack user mentions and surrounding whitespace. */
+export function stripLeadingSlackMentions(text: string): string {
+  let current = text.trim();
+  while (MENTION_RE.test(current)) {
+    current = current.replace(MENTION_RE, "").trim();
+  }
+  return current;
+}
+
+/**
+ * True when the message (after stripping @mentions) is exactly `stop`
+ * (case-insensitive).
+ */
+export function isWholeMessageStop(text: string): boolean {
+  return stripLeadingSlackMentions(text).toLowerCase() === "stop";
+}

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

@@ -0,0 +1,572 @@
+/**
+ * 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 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;
+}
+
+/** Pull readable text out of Slack attachment / Block Kit payloads. */
+export function slackApiMessageBody(message: JsonRecord): string {
+  const parts: string[] = [];
+  const text = asString(message.text);
+  if (text !== undefined && text.trim() !== "") {
+    parts.push(text);
+  }
+
+  const attachments = Array.isArray(message.attachments)
+    ? message.attachments
+    : [];
+  for (const attachment of attachments) {
+    const rec = asRecord(attachment);
+    if (rec === null) {
+      continue;
+    }
+    for (const key of [
+      "pretext",
+      "title",
+      "text",
+      "fallback",
+      "footer",
+    ] as const) {
+      const value = asString(rec[key]);
+      if (value !== undefined && value.trim() !== "") {
+        parts.push(value);
+      }
+    }
+    const titleLink = asString(rec.title_link);
+    if (titleLink !== undefined && titleLink.trim() !== "") {
+      parts.push(titleLink);
+    }
+  }
+
+  const blocks = Array.isArray(message.blocks) ? message.blocks : [];
+  for (const block of blocks) {
+    const rec = asRecord(block);
+    if (rec === null) {
+      continue;
+    }
+    const blockText = asRecord(rec.text);
+    const blockTextValue = asString(blockText?.text);
+    if (blockTextValue !== undefined && blockTextValue.trim() !== "") {
+      parts.push(blockTextValue);
+    }
+    const fields = Array.isArray(rec.fields) ? rec.fields : [];
+    for (const field of fields) {
+      const fieldRec = asRecord(field);
+      const fieldText = asString(fieldRec?.text);
+      if (fieldText !== undefined && fieldText.trim() !== "") {
+        parts.push(fieldText);
+      }
+    }
+  }
+
+  // Dedupe identical chunks (Datadog often repeats text/fallback across fields).
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed === "" || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    deduped.push(trimmed);
+  }
+  return deduped.join("\n");
+}
+
+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/types.ts

@@ -62,6 +62,11 @@ export interface SlackChannelState {
   streamChannelId?: string | null;
   /** Last cumulative text sent via appendStream (for incremental append). */
   lastPostedText?: string | null;
+  /**
+   * Slack message ts of the agent's last delivered reply in this thread.
+   * Warm turns use this as the `<slack_thread_delta>` watermark.
+   */
+  lastBotMessageTs?: string | null;
   /**
    * When true, stream APIs failed for this session — use postMessage
    * for the rest of the turn.
@@ -75,9 +80,12 @@ export interface SlackChannelState {
 }
 
 export interface SlackAuthor {
+  /** Slack user id. Empty string for bot posts with no `user` field. */
   userId: string;
   userName?: string;
   isBot: boolean;
+  /** Posting app's `bot_id` (`B…`) when the message is bot-authored. */
+  botId?: string;
 }
 
 export interface SlackMessage {
@@ -125,6 +133,11 @@ export interface SlackDispatchDecision {
    * cloud conversation (e.g. per-PR `bc-…` affinity).
    */
   sdkAgentId?: string;
+  /**
+   * Additional Slack message timestamps to omit from `<slack_thread>` hydration
+   * (e.g. every message in a coalesced batch already folded into `message`).
+   */
+  excludeThreadTimestamps?: readonly string[];
 }
 
 export interface SlackSuggestedPrompt {
@@ -191,6 +204,13 @@ export interface SlackChannelPostsOptions {
    * the Cursor relay does not deliver edits/deletes.
    */
   debounceMs?: number;
+  /**
+   * Also dispatch bot-authored posts (alert feeds, webhook integrations,
+   * other agents posting notes). Defaults to `false` — human posts only.
+   * The watching bot's own posts are always dropped regardless (loop
+   * safety), matched by the app's `bot_id` / bot user id from `auth.test`.
+   */
+  includeBotPosts?: boolean;
 }
 
 /**
@@ -357,6 +377,13 @@ export interface SlackChannelOptions {
    */
   suggestedPrompts?: SlackSuggestedPrompt[];
   suggestedPromptsTitle?: string;
+  /**
+   * Rotating `assistant.threads.setStatus` loading lines (Slack caps each
+   * entry at 50 chars). Defaults to Thinking… / Working on it… / Almost there….
+   */
+  loadingMessages?: string[];
+  /** Optional teardown (e.g. stop example-local debouncers). Runs after Socket Mode stops. */
+  onStop?: () => void | Promise<void>;
 }
 
 export interface SlackManifestOptions {