@cursor/july 0.1.20 → 0.1.22

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

@@ -0,0 +1,267 @@
+import { describe, expect, it } from "vitest";
+import {
+  botMentionsFromEnv,
+  buildDelegationMetadata,
+  normalizeBotMentionAllowlist,
+  parseDelegationMetadata,
+  SLACK_DELEGATION_METADATA_EVENT_TYPE,
+  SlackBotMentionGate,
+} from "./bot-mentions.js";
+import { parseAppMentionEvent } from "./inbound.js";
+import type { SlackMessage } from "./types.js";
+
+function botMention(patch: Partial<SlackMessage> = {}): SlackMessage {
+  return {
+    text: "<@ULASSO> please deploy #123",
+    body: "<@ULASSO> please deploy #123",
+    markdown: "@ULASSO please deploy #123",
+    ts: "2.0",
+    threadTs: "1.0",
+    channelId: "C9",
+    author: { userId: "ULASSO", isBot: true, botId: "BLASSO" },
+    ...patch,
+  };
+}
+
+function gate(
+  options: Partial<ConstructorParameters<typeof SlackBotMentionGate>[0]> = {},
+  identity: { botId?: string; botUserId?: string } = {
+    botId: "BSELF",
+    botUserId: "USELF",
+  }
+): SlackBotMentionGate {
+  return new SlackBotMentionGate(
+    { allowFrom: ["BLASSO"], ...options },
+    identity,
+    { log: { info() {}, warn() {}, error() {}, debug() {}, write() {} } }
+  );
+}
+
+describe("delegation metadata", () => {
+  it("round-trips build → parse", () => {
+    const metadata = buildDelegationMetadata({
+      depth: 2,
+      fromAgent: "lasso",
+      originSessionId: "sess-1",
+    });
+    expect(metadata.event_type).toBe(SLACK_DELEGATION_METADATA_EVENT_TYPE);
+    const parsed = parseDelegationMetadata({ metadata });
+    expect(parsed).toEqual({
+      depth: 2,
+      fromAgent: "lasso",
+      originSessionId: "sess-1",
+    });
+  });
+
+  it("ignores foreign and malformed metadata", () => {
+    expect(parseDelegationMetadata({})).toBeUndefined();
+    expect(
+      parseDelegationMetadata({
+        metadata: { event_type: "other", event_payload: { depth: 1 } },
+      })
+    ).toBeUndefined();
+    expect(
+      parseDelegationMetadata({
+        metadata: {
+          event_type: SLACK_DELEGATION_METADATA_EVENT_TYPE,
+          event_payload: { depth: 0 },
+        },
+      })
+    ).toBeUndefined();
+    expect(
+      parseDelegationMetadata({
+        metadata: {
+          event_type: SLACK_DELEGATION_METADATA_EVENT_TYPE,
+          event_payload: { depth: "two" },
+        },
+      })
+    ).toBeUndefined();
+  });
+});
+
+describe("botMentionsFromEnv", () => {
+  it("returns undefined when unset and options when set", () => {
+    const envVar = "BOT_MENTIONS_TEST_VAR";
+    delete process.env[envVar];
+    expect(botMentionsFromEnv(envVar)).toBeUndefined();
+    process.env[envVar] = " B1 ,,U2 ";
+    expect(botMentionsFromEnv(envVar)).toEqual({ allowFrom: ["B1", "U2"] });
+    delete process.env[envVar];
+  });
+});
+
+describe("parseAppMentionEvent bot-authored", () => {
+  const body = {
+    type: "event_callback",
+    team_id: "T1",
+    event: {
+      type: "app_mention",
+      user: "ULASSO",
+      bot_id: "BLASSO",
+      text: "<@UTARGET> look into this",
+      ts: "2.0",
+      thread_ts: "1.0",
+      channel: "C9",
+      metadata: buildDelegationMetadata({ depth: 1, fromAgent: "lasso" }),
+    },
+  };
+
+  it("drops bot mentions by default", () => {
+    expect(parseAppMentionEvent(body)).toBeNull();
+  });
+
+  it("keeps bot mentions with delegation info when opted in", () => {
+    const message = parseAppMentionEvent(body, { includeBotAuthored: true });
+    expect(message).not.toBeNull();
+    expect(message?.author?.isBot).toBe(true);
+    expect(message?.author?.botId).toBe("BLASSO");
+    expect(message?.delegation).toEqual({ depth: 1, fromAgent: "lasso" });
+  });
+
+  it("still parses human mentions when opted in", () => {
+    const message = parseAppMentionEvent(
+      {
+        type: "event_callback",
+        event: {
+          type: "app_mention",
+          user: "U1",
+          text: "<@UTARGET> hi",
+          ts: "3.0",
+          channel: "C9",
+        },
+      },
+      { includeBotAuthored: true }
+    );
+    expect(message?.author?.isBot).toBe(false);
+    expect(message?.delegation).toBeUndefined();
+  });
+});
+
+describe("normalizeBotMentionAllowlist", () => {
+  it("trims entries and rejects empty lists", () => {
+    expect(normalizeBotMentionAllowlist([" B1 ", "U2"])).toEqual(["B1", "U2"]);
+    expect(() => normalizeBotMentionAllowlist([" "])).toThrow(/allowFrom/);
+  });
+});
+
+describe("SlackBotMentionGate", () => {
+  it("requires its own bot identity", () => {
+    expect(() => gate({}, {})).toThrow(/identity/);
+  });
+
+  it("admits an allowlisted bot mention", () => {
+    const verdict = gate().evaluate(botMention());
+    expect(verdict).toEqual({ allow: true, depth: 1 });
+  });
+
+  it("matches on bot user id as well as bot_id", () => {
+    const verdict = gate({ allowFrom: ["ULASSO"] }).evaluate(botMention());
+    expect(verdict.allow).toBe(true);
+  });
+
+  it("matches compound botId:username entries case-insensitively", () => {
+    const g = gate({ allowFrom: ["BCURSOR:Lasso"] });
+    const fromCursorAsLasso = botMention({
+      author: {
+        userId: "UCURSOR",
+        isBot: true,
+        botId: "BCURSOR",
+        userName: "lasso",
+      },
+    });
+    expect(g.evaluate(fromCursorAsLasso).allow).toBe(true);
+  });
+
+  it("compound entries deny other usernames and missing usernames", () => {
+    const g = gate({ allowFrom: ["BCURSOR:Lasso"] });
+    expect(
+      g.evaluate(
+        botMention({
+          author: {
+            userId: "UCURSOR",
+            isBot: true,
+            botId: "BCURSOR",
+            userName: "SomeOtherAgent",
+          },
+        })
+      )
+    ).toMatchObject({ allow: false });
+    // No username on the event → fail closed.
+    expect(
+      g.evaluate(
+        botMention({
+          author: { userId: "UCURSOR", isBot: true, botId: "BCURSOR" },
+        })
+      )
+    ).toMatchObject({ allow: false });
+    // Bare bot_id was not allowlisted, only the compound form.
+    expect(
+      g.evaluate(
+        botMention({
+          author: {
+            userId: "UCURSOR",
+            isBot: true,
+            botId: "BCURSOR",
+            userName: undefined,
+          },
+        })
+      )
+    ).toMatchObject({ allow: false });
+  });
+
+  it("denies bots not in the allowlist", () => {
+    const verdict = gate().evaluate(
+      botMention({ author: { userId: "UOTHER", isBot: true, botId: "BOTHER" } })
+    );
+    expect(verdict).toMatchObject({ allow: false });
+  });
+
+  it("denies its own posts even when allowlisted", () => {
+    const verdict = gate({ allowFrom: ["BSELF"] }).evaluate(
+      botMention({ author: { userId: "USELF", isBot: true, botId: "BSELF" } })
+    );
+    expect(verdict).toMatchObject({ allow: false, reason: /own post/ });
+  });
+
+  it("enforces the depth budget", () => {
+    const g = gate();
+    expect(g.evaluate(botMention({ delegation: { depth: 2 } })).allow).toBe(
+      true
+    );
+    expect(
+      g.evaluate(botMention({ ts: "3.0", delegation: { depth: 3 } }))
+    ).toMatchObject({ allow: false, reason: /depth/ });
+  });
+
+  it("enforces the rate budget with a sliding window", () => {
+    const g = gate({ maxPerThreadPerHour: 2 });
+    expect(g.evaluate(botMention(), 1000).allow).toBe(true);
+    expect(g.evaluate(botMention(), 2000).allow).toBe(true);
+    expect(g.evaluate(botMention(), 3000)).toMatchObject({
+      allow: false,
+      reason: /rate budget/,
+    });
+    // Window slides: an hour later the thread has rate budget again.
+    const later = 3000 + 60 * 60 * 1000;
+    expect(g.evaluate(botMention(), later).allow).toBe(true);
+    // Other threads are unaffected.
+    expect(g.evaluate(botMention({ threadTs: "9.0" }), 3000).allow).toBe(true);
+  });
+
+  it("terminates ping-pong with the lifetime thread cap", () => {
+    const g = gate({ maxPerThreadPerHour: 100, maxPerThreadTotal: 3 });
+    expect(g.evaluate(botMention(), 1000).allow).toBe(true);
+    expect(g.evaluate(botMention(), 2000).allow).toBe(true);
+    expect(g.evaluate(botMention(), 3000).allow).toBe(true);
+    expect(g.evaluate(botMention(), 4000)).toMatchObject({
+      allow: false,
+      reason: /lifetime/,
+    });
+    // Sliding the window does NOT refill the lifetime cap.
+    const muchLater = 4000 + 5 * 60 * 60 * 1000;
+    expect(g.evaluate(botMention(), muchLater)).toMatchObject({
+      allow: false,
+      reason: /lifetime/,
+    });
+  });
+});

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

@@ -0,0 +1,339 @@
+/**
+ * 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>;
+  /** Compound entries: posting `bot_id` → allowed lowercase usernames. */
+  private readonly allowFromCompound: Map<string, 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();
+    this.allowFromCompound = new Map();
+    for (const entry of normalizeBotMentionAllowlist(options.allowFrom)) {
+      const separator = entry.indexOf(":");
+      if (separator <= 0 || separator === entry.length - 1) {
+        this.allowFrom.add(entry);
+        continue;
+      }
+      const botId = entry.slice(0, separator);
+      const username = entry.slice(separator + 1).toLowerCase();
+      const usernames = this.allowFromCompound.get(botId) ?? new Set();
+      usernames.add(username);
+      this.allowFromCompound.set(botId, usernames);
+    }
+    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 compoundUsernames =
+      author.botId === undefined
+        ? undefined
+        : this.allowFromCompound.get(author.botId);
+    const allowed =
+      (author.botId !== undefined && this.allowFrom.has(author.botId)) ||
+      (author.userId !== "" && this.allowFrom.has(author.userId)) ||
+      // Compound entry: shared app bot_id + server-pinned username. Fails
+      // closed when the event carries no username.
+      (compoundUsernames !== undefined &&
+        author.userName !== undefined &&
+        compoundUsernames.has(author.userName.toLowerCase()));
+    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 };
+}