@cursor/july 0.1.19 → 0.1.21

package/src/channels/slack/bot-mentions.ts

@@ -0,0 +1,315 @@
+/**
+ * Opt-in bot-to-bot mention wake (`engagement.botMentions`).
+ *
+ * Layered loop protection, any one of which blocks a runaway chain:
+ * 1. Allowlist — only mentions from explicitly trusted bots wake the agent.
+ * 2. Own-post filter — the agent's own posts never wake it (always on).
+ * 3. Depth budget — delegation metadata carries a hop count; mentions
+ *    without metadata count as depth 1. Default max is 2.
+ * 4. Thread budgets — a sliding-window rate cap plus a lifetime total per
+ *    thread, so undetected ping-pong between trusted bots terminates
+ *    instead of merely slowing down.
+ */
+
+import { postMessage } from "./api.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import type {
+  SlackBotMentionsOptions,
+  SlackBotToken,
+  SlackDelegationInfo,
+  SlackMessage,
+} from "./types.js";
+
+/** Slack message `metadata.event_type` for agentkit delegation posts. */
+export const SLACK_DELEGATION_METADATA_EVENT_TYPE = "agentkit_delegation";
+
+/** Default budgets for {@link SlackBotMentionsOptions}. */
+export const SLACK_BOT_MENTION_DEFAULTS = {
+  maxDepth: 2,
+  maxPerThreadPerHour: 5,
+  maxPerThreadTotal: 20,
+} as const;
+
+const THREAD_BUDGET_WINDOW_MS = 60 * 60 * 1000;
+/** Threads idle this long are evicted (their lifetime budget resets). */
+const THREAD_IDLE_EVICT_MS = 24 * 60 * 60 * 1000;
+/** Eviction sweep runs when the thread map grows past this many keys. */
+const THREAD_SWEEP_THRESHOLD = 512;
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+/**
+ * Parse delegation metadata off a raw Slack event (`event.metadata`).
+ * Returns undefined for absent, foreign, or malformed metadata.
+ */
+export function parseDelegationMetadata(
+  event: unknown
+): SlackDelegationInfo | undefined {
+  const root = asRecord(event);
+  const metadata = asRecord(root?.metadata);
+  if (
+    metadata === null ||
+    metadata.event_type !== SLACK_DELEGATION_METADATA_EVENT_TYPE
+  ) {
+    return undefined;
+  }
+  const payload = asRecord(metadata.event_payload);
+  if (payload === null) {
+    return undefined;
+  }
+  const depth =
+    typeof payload.depth === "number" && Number.isFinite(payload.depth)
+      ? Math.floor(payload.depth)
+      : undefined;
+  if (depth === undefined || depth < 1) {
+    return undefined;
+  }
+  const info: SlackDelegationInfo = { depth };
+  if (typeof payload.from_agent === "string" && payload.from_agent !== "") {
+    info.fromAgent = payload.from_agent;
+  }
+  if (
+    typeof payload.origin_session_id === "string" &&
+    payload.origin_session_id !== ""
+  ) {
+    info.originSessionId = payload.origin_session_id;
+  }
+  return info;
+}
+
+/** Build the Slack `metadata` body for an outbound delegation post. */
+export function buildDelegationMetadata(args: {
+  depth: number;
+  fromAgent?: string;
+  originSessionId?: string;
+}): Record<string, unknown> {
+  const payload: Record<string, unknown> = { depth: args.depth };
+  if (args.fromAgent !== undefined && args.fromAgent !== "") {
+    payload.from_agent = args.fromAgent;
+  }
+  if (args.originSessionId !== undefined && args.originSessionId !== "") {
+    payload.origin_session_id = args.originSessionId;
+  }
+  return {
+    event_type: SLACK_DELEGATION_METADATA_EVENT_TYPE,
+    event_payload: payload,
+  };
+}
+
+/**
+ * Validate and normalize a `botMentions.allowFrom` list. Shared by channel
+ * construction (fail at definition time) and the gate (fail at start).
+ */
+export function normalizeBotMentionAllowlist(
+  allowFrom: readonly string[]
+): string[] {
+  const entries = allowFrom
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "");
+  if (entries.length === 0) {
+    throw new Error(
+      "slackChannel engagement.botMentions.allowFrom must list at least one bot id (B…) or bot user id (U…); there is no wildcard."
+    );
+  }
+  return entries;
+}
+
+/**
+ * Read `engagement.botMentions` options from the environment: a
+ * comma-separated bot-id allowlist in `AGENT_DELEGATOR_SLACK_BOT_IDS` (or a
+ * custom var). Returns undefined when unset, so channels can pass the
+ * result straight through and stay bot-mention-free by default:
+ *
+ * ```ts
+ * engagement: { botMentions: botMentionsFromEnv() }
+ * ```
+ */
+export function botMentionsFromEnv(
+  envVar = "AGENT_DELEGATOR_SLACK_BOT_IDS"
+): SlackBotMentionsOptions | undefined {
+  const allowFrom = (process.env[envVar] ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "");
+  return allowFrom.length === 0 ? undefined : { allowFrom };
+}
+
+export type SlackBotMentionVerdict =
+  | { allow: true; depth: number }
+  | { allow: false; reason: string };
+
+interface ThreadBudget {
+  /** Lifetime admitted wakes for this thread (until idle eviction). */
+  total: number;
+  /** Timestamps of recent admitted wakes (pruned to the window). */
+  recent: number[];
+  lastAtMs: number;
+}
+
+/**
+ * Admission gate for bot-authored mentions. One instance per channel;
+ * thread budgets are in-memory (reset on restart — acceptable, the depth
+ * and allowlist layers do not depend on process state). Threads idle for
+ * 24h are evicted, which also resets their lifetime budget.
+ */
+export class SlackBotMentionGate {
+  private readonly allowFrom: Set<string>;
+  private readonly maxDepth: number;
+  private readonly maxPerThreadPerHour: number;
+  private readonly maxPerThreadTotal: number;
+  private readonly windowMs: number;
+  private readonly threadBudgets = new Map<string, ThreadBudget>();
+  private readonly log: SlackLog;
+
+  constructor(
+    options: SlackBotMentionsOptions,
+    private readonly identity: { botUserId?: string; botId?: string },
+    args?: { log?: SlackLog; windowMs?: number }
+  ) {
+    if (identity.botUserId === undefined && identity.botId === undefined) {
+      throw new Error(
+        "SlackBotMentionGate requires the agent's own bot identity (auth.test) for loop safety."
+      );
+    }
+    this.allowFrom = new Set(normalizeBotMentionAllowlist(options.allowFrom));
+    this.maxDepth = options.maxDepth ?? SLACK_BOT_MENTION_DEFAULTS.maxDepth;
+    this.maxPerThreadPerHour =
+      options.maxPerThreadPerHour ??
+      SLACK_BOT_MENTION_DEFAULTS.maxPerThreadPerHour;
+    this.maxPerThreadTotal =
+      options.maxPerThreadTotal ?? SLACK_BOT_MENTION_DEFAULTS.maxPerThreadTotal;
+    this.windowMs = args?.windowMs ?? THREAD_BUDGET_WINDOW_MS;
+    this.log = args?.log ?? defaultSlackLog;
+  }
+
+  /**
+   * Evaluate a bot-authored mention. Callers must only pass messages whose
+   * author `isBot`; human mentions never consult the gate. An `allow`
+   * verdict consumes thread budget.
+   */
+  evaluate(
+    message: SlackMessage,
+    nowMs: number = Date.now()
+  ): SlackBotMentionVerdict {
+    const author = message.author;
+    if (author === undefined || !author.isBot) {
+      return { allow: false, reason: "not bot-authored" };
+    }
+
+    // Own posts never wake the agent, allowlisted or not.
+    if (
+      (this.identity.botId !== undefined &&
+        author.botId === this.identity.botId) ||
+      (this.identity.botUserId !== undefined &&
+        author.userId !== "" &&
+        author.userId === this.identity.botUserId)
+    ) {
+      return { allow: false, reason: "own post (loop safety)" };
+    }
+
+    const allowed =
+      (author.botId !== undefined && this.allowFrom.has(author.botId)) ||
+      (author.userId !== "" && this.allowFrom.has(author.userId));
+    if (!allowed) {
+      return { allow: false, reason: "author not in botMentions.allowFrom" };
+    }
+
+    const depth = message.delegation?.depth ?? 1;
+    if (depth > this.maxDepth) {
+      return {
+        allow: false,
+        reason: `delegation depth ${depth} exceeds max ${this.maxDepth}`,
+      };
+    }
+
+    this.maybeEvictIdleThreads(nowMs);
+    const key = `${message.channelId}:${message.threadTs}`;
+    const budget = this.threadBudgets.get(key) ?? {
+      total: 0,
+      recent: [],
+      lastAtMs: nowMs,
+    };
+    budget.recent = budget.recent.filter(
+      (atMs) => atMs > nowMs - this.windowMs
+    );
+    if (budget.total >= this.maxPerThreadTotal) {
+      return {
+        allow: false,
+        reason: `thread lifetime budget exhausted (${this.maxPerThreadTotal})`,
+      };
+    }
+    if (budget.recent.length >= this.maxPerThreadPerHour) {
+      return {
+        allow: false,
+        reason: `thread rate budget exhausted (${this.maxPerThreadPerHour}/window)`,
+      };
+    }
+    budget.total += 1;
+    budget.recent.push(nowMs);
+    budget.lastAtMs = nowMs;
+    this.threadBudgets.set(key, budget);
+    this.log.info("bot mention admitted", {
+      channel: message.channelId,
+      thread_ts: message.threadTs,
+      from_bot: author.botId ?? author.userId,
+      depth,
+      thread_total: budget.total,
+    });
+    return { allow: true, depth };
+  }
+
+  private maybeEvictIdleThreads(nowMs: number): void {
+    if (this.threadBudgets.size < THREAD_SWEEP_THRESHOLD) {
+      return;
+    }
+    for (const [key, budget] of this.threadBudgets) {
+      if (nowMs - budget.lastAtMs > THREAD_IDLE_EVICT_MS) {
+        this.threadBudgets.delete(key);
+      }
+    }
+  }
+}
+
+/**
+ * Post an @mention of another bot with delegation metadata attached, so the
+ * target's `engagement.botMentions` gate can read the hop count. Use this
+ * from dispatcher tools instead of a bare `chat.postMessage`.
+ */
+export async function postDelegationMention(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  /** Target bot's Slack *user* id (`U…`) — what `<@…>` mentions require. */
+  targetUserId: string;
+  text: string;
+  threadTs?: string;
+  /** Defaults to 1 (dispatcher woken by a human). */
+  depth?: number;
+  fromAgent?: string;
+  originSessionId?: string;
+}): Promise<{ ts: string }> {
+  const posted = await postMessage({
+    botToken: args.botToken,
+    channel: args.channelId,
+    text: `<@${args.targetUserId}> ${args.text}`.trim(),
+    threadTs: args.threadTs,
+    // Mention markup only notifies via mrkdwn `text`, and metadata must
+    // ride the same chat.postMessage call.
+    plainText: true,
+    metadata: buildDelegationMetadata({
+      depth: args.depth ?? 1,
+      fromAgent: args.fromAgent,
+      originSessionId: args.originSessionId,
+    }),
+  });
+  if (posted.ts === "") {
+    throw new Error(
+      "Slack delegation mention posted without a message ts; cannot track the handoff."
+    );
+  }
+  return { ts: posted.ts };
+}

package/src/channels/slack/channel-watch.test.ts

@@ -0,0 +1,363 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createChannelPostWatcher,
+  SlackChannelAllowlist,
+} from "./channel-watch.js";
+import {
+  parseChannelMessageEvent,
+  type SlackChannelMessageEvent,
+} from "./inbound.js";
+import type { SlackMessage } from "./types.js";
+
+function channelPostBody(args: {
+  channel?: string;
+  ts?: string;
+  threadTs?: string;
+  text?: string;
+  subtype?: string;
+  botId?: string;
+  channelType?: string;
+  user?: string | null;
+}): unknown {
+  return {
+    type: "event_callback",
+    event_id: "Ev1",
+    team_id: "T1",
+    event: {
+      type: "message",
+      channel: args.channel ?? "C123",
+      channel_type: args.channelType ?? "channel",
+      ts: args.ts ?? "100.1",
+      ...(args.threadTs === undefined ? {} : { thread_ts: args.threadTs }),
+      text: args.text ?? "new bug report",
+      ...(args.user === null ? {} : { user: args.user ?? "U1" }),
+      ...(args.subtype === undefined ? {} : { subtype: args.subtype }),
+      ...(args.botId === undefined ? {} : { bot_id: args.botId }),
+    },
+  };
+}
+
+describe("parseChannelMessageEvent", () => {
+  it("parses a top-level channel post", () => {
+    const parsed = parseChannelMessageEvent(channelPostBody({}));
+    expect(parsed).not.toBeNull();
+    expect(parsed?.kind).toBe("post");
+    if (parsed?.kind === "post") {
+      expect(parsed.message.channelId).toBe("C123");
+      expect(parsed.message.ts).toBe("100.1");
+      expect(parsed.message.threadTs).toBe("100.1");
+    }
+  });
+
+  it("parses private-channel (group) posts", () => {
+    const parsed = parseChannelMessageEvent(
+      channelPostBody({ channel: "G9", channelType: "group" })
+    );
+    expect(parsed?.kind).toBe("post");
+  });
+
+  it("drops bot-authored posts", () => {
+    expect(
+      parseChannelMessageEvent(channelPostBody({ botId: "B77" }))
+    ).toBeNull();
+  });
+
+  it("keeps bot-authored posts when includeBotAuthored is set", () => {
+    const parsed = parseChannelMessageEvent(channelPostBody({ botId: "B77" }), {
+      includeBotAuthored: true,
+    });
+    expect(parsed?.kind).toBe("post");
+    if (parsed?.kind === "post") {
+      expect(parsed.message.author?.isBot).toBe(true);
+      expect(parsed.message.author?.botId).toBe("B77");
+    }
+  });
+
+  it("keeps userless bot_message webhook posts when includeBotAuthored is set", () => {
+    const body = channelPostBody({
+      botId: "B77",
+      subtype: "bot_message",
+      user: null,
+      text: "PagerDuty: high error rate on api",
+    });
+    expect(parseChannelMessageEvent(body)).toBeNull();
+    const parsed = parseChannelMessageEvent(body, {
+      includeBotAuthored: true,
+    });
+    expect(parsed?.kind).toBe("post");
+    if (parsed?.kind === "post") {
+      expect(parsed.message.author).toEqual({
+        userId: "",
+        isBot: true,
+        botId: "B77",
+      });
+    }
+  });
+
+  it("recovers alert content from attachments when top-level text is empty", () => {
+    const parsed = parseChannelMessageEvent(
+      {
+        type: "event_callback",
+        team_id: "T1",
+        event: {
+          type: "message",
+          subtype: "bot_message",
+          channel: "C123",
+          channel_type: "channel",
+          ts: "100.1",
+          bot_id: "B77",
+          username: "Datadog",
+          text: "",
+          attachments: [
+            {
+              title:
+                "Triggered: [service-monitor prod:temporal-bugbot] High cache error rate",
+              title_link: "https://us5.datadoghq.com/monitors/19610160",
+              text: "Service temporal-bugbot has a high cache error rate.",
+            },
+          ],
+        },
+      },
+      { includeBotAuthored: true }
+    );
+    expect(parsed?.kind).toBe("post");
+    if (parsed?.kind === "post") {
+      expect(parsed.message.text).toBe("");
+      expect(parsed.message.body).toContain("temporal-bugbot");
+      // Raw body keeps the monitor link; markdown is the model-facing view.
+      expect(parsed.message.body).toContain(
+        "https://us5.datadoghq.com/monitors/19610160"
+      );
+      expect(parsed.message.markdown).toContain("High cache error rate");
+    }
+  });
+
+  it("drops DMs and unknown subtypes", () => {
+    expect(
+      parseChannelMessageEvent(
+        channelPostBody({ channel: "D5", channelType: "im" })
+      )
+    ).toBeNull();
+    expect(
+      parseChannelMessageEvent(channelPostBody({ subtype: "channel_join" }))
+    ).toBeNull();
+  });
+
+  it("parses message_changed into an edit with the new text", () => {
+    const parsed = parseChannelMessageEvent({
+      type: "event_callback",
+      event: {
+        type: "message",
+        subtype: "message_changed",
+        channel: "C123",
+        channel_type: "channel",
+        ts: "101.0",
+        message: { type: "message", ts: "100.1", text: "edited!", user: "U1" },
+      },
+    });
+    expect(parsed?.kind).toBe("edited");
+    if (parsed?.kind === "edited") {
+      expect(parsed.message.ts).toBe("100.1");
+      expect(parsed.message.text).toBe("edited!");
+    }
+  });
+
+  it("parses message_deleted into a deletion", () => {
+    const parsed = parseChannelMessageEvent({
+      type: "event_callback",
+      event: {
+        type: "message",
+        subtype: "message_deleted",
+        channel: "C123",
+        channel_type: "channel",
+        ts: "101.0",
+        deleted_ts: "100.1",
+      },
+    });
+    expect(parsed).toEqual({ kind: "deleted", channelId: "C123", ts: "100.1" });
+  });
+});
+
+describe("SlackChannelAllowlist", () => {
+  it("matches ids directly and names after resolution", () => {
+    const allowlist = new SlackChannelAllowlist(["C123", "#issues-glass"]);
+    expect(allowlist.matches("C123")).toBe(true);
+    expect(allowlist.matches("C999")).toBe(false);
+    expect(allowlist.unresolvedNames()).toEqual(["issues-glass"]);
+    allowlist.applyResolvedNames(new Map([["issues-glass", "C999"]]));
+    expect(allowlist.matches("C999")).toBe(true);
+  });
+
+  it("treats bare names as names, not ids", () => {
+    const allowlist = new SlackChannelAllowlist(["issues-glass"]);
+    expect(allowlist.unresolvedNames()).toEqual(["issues-glass"]);
+  });
+});
+
+describe("createChannelPostWatcher", () => {
+  const dispatched: Array<{ message: SlackMessage; eventId?: string }> = [];
+
+  function watcher(args?: {
+    posts?: "top-level" | "all";
+    debounceMs?: number;
+    includeBotPosts?: boolean;
+    botUserId?: string;
+    botId?: string;
+    allow?: string[];
+  }) {
+    return createChannelPostWatcher({
+      options: {
+        allow: args?.allow ?? ["C123"],
+        ...(args?.posts === undefined ? {} : { posts: args.posts }),
+        ...(args?.debounceMs === undefined
+          ? {}
+          : { debounceMs: args.debounceMs }),
+        ...(args?.includeBotPosts === undefined
+          ? {}
+          : { includeBotPosts: args.includeBotPosts }),
+      },
+      allowlist: new SlackChannelAllowlist(args?.allow ?? ["C123"]),
+      getBotUserId: () => args?.botUserId,
+      getBotId: () => args?.botId,
+      dispatch: (message, eventId) =>
+        dispatched.push(
+          eventId === undefined ? { message } : { message, eventId }
+        ),
+    });
+  }
+
+  function post(args: {
+    channel?: string;
+    ts?: string;
+    threadTs?: string;
+    text?: string;
+    subtype?: string;
+    botId?: string;
+    user?: string | null;
+  }): SlackChannelMessageEvent {
+    const parsed = parseChannelMessageEvent(channelPostBody(args), {
+      includeBotAuthored: true,
+    });
+    if (parsed === null) {
+      throw new Error("fixture did not parse");
+    }
+    return parsed;
+  }
+
+  beforeEach(() => {
+    dispatched.length = 0;
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("dispatches allowlisted top-level posts immediately by default", () => {
+    const w = watcher();
+    expect(w.handle(post({}), "Ev1")).toBe(true);
+    expect(dispatched).toHaveLength(1);
+    expect(dispatched[0]?.eventId).toBe("Ev1");
+  });
+
+  it("skips channels outside the allowlist", () => {
+    const w = watcher();
+    w.handle(post({ channel: "C999" }));
+    expect(dispatched).toHaveLength(0);
+  });
+
+  it("skips thread replies unless posts is 'all'", () => {
+    const w = watcher();
+    w.handle(post({ ts: "100.2", threadTs: "100.1" }));
+    expect(dispatched).toHaveLength(0);
+
+    const all = watcher({ posts: "all" });
+    all.handle(post({ ts: "100.2", threadTs: "100.1" }));
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("skips posts that mention the bot (app_mention path owns them)", () => {
+    const w = watcher({ botUserId: "UBOT" });
+    w.handle(post({ text: "<@UBOT> please triage" }));
+    expect(dispatched).toHaveLength(0);
+  });
+
+  it("skips bot-authored posts unless includeBotPosts is set", () => {
+    const w = watcher();
+    w.handle(post({ botId: "B77", user: null, subtype: "bot_message" }));
+    expect(dispatched).toHaveLength(0);
+
+    const withBots = watcher({
+      includeBotPosts: true,
+      botId: "BSELF",
+      botUserId: "UBOT",
+    });
+    withBots.handle(post({ botId: "B77", user: null, subtype: "bot_message" }));
+    expect(dispatched).toHaveLength(1);
+    expect(dispatched[0]?.message.author?.botId).toBe("B77");
+  });
+
+  it("skips bot-authored posts when includeBotPosts is on but bot identity is unknown", () => {
+    const w = watcher({ includeBotPosts: true });
+    w.handle(post({ botId: "B77", user: null, subtype: "bot_message" }));
+    expect(dispatched).toHaveLength(0);
+  });
+
+  it("always skips the watching bot's own posts (loop safety)", () => {
+    const w = watcher({
+      includeBotPosts: true,
+      botUserId: "UBOT",
+      botId: "BSELF",
+    });
+    w.handle(post({ botId: "BSELF", user: null, subtype: "bot_message" }));
+    expect(dispatched).toHaveLength(0);
+
+    // Same app posting with its bot user id attached.
+    w.handle(post({ botId: "B99", user: "UBOT" }));
+    expect(dispatched).toHaveLength(0);
+
+    // A different bot still dispatches.
+    w.handle(post({ botId: "B77", user: null, subtype: "bot_message" }));
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("debounces: edits update the pending text, deletes cancel", () => {
+    vi.useFakeTimers();
+    const w = watcher({ debounceMs: 1_000 });
+
+    w.handle(post({ ts: "100.1", text: "first" }));
+    expect(dispatched).toHaveLength(0);
+    const edit = parseChannelMessageEvent({
+      type: "event_callback",
+      event: {
+        type: "message",
+        subtype: "message_changed",
+        channel: "C123",
+        channel_type: "channel",
+        ts: "101.0",
+        message: { type: "message", ts: "100.1", text: "edited", user: "U1" },
+      },
+    });
+    if (edit === null) {
+      throw new Error("edit fixture did not parse");
+    }
+    w.handle(edit);
+    vi.advanceTimersByTime(1_000);
+    expect(dispatched).toHaveLength(1);
+    expect(dispatched[0]?.message.text).toBe("edited");
+
+    w.handle(post({ ts: "200.1", text: "will be deleted" }));
+    w.handle({ kind: "deleted", channelId: "C123", ts: "200.1" });
+    vi.advanceTimersByTime(5_000);
+    expect(dispatched).toHaveLength(1);
+
+    w.stop();
+  });
+
+  it("stop() cancels pending dispatches", () => {
+    vi.useFakeTimers();
+    const w = watcher({ debounceMs: 1_000 });
+    w.handle(post({}));
+    w.stop();
+    vi.advanceTimersByTime(5_000);
+    expect(dispatched).toHaveLength(0);
+  });
+});