@cursor/bdk 0.2.1

package/dist/channels/slack/blocks.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Block Kit building helpers shared by card-building agents.
+ */
+/** Slack cap for one section block's mrkdwn text. */
+export declare const SLACK_SECTION_MRKDWN_MAX = 3000;
+/** Slack caps for a native `table` block (one table per message). */
+export declare const SLACK_TABLE_MAX_ROWS = 100;
+export declare const SLACK_TABLE_MAX_COLUMNS = 20;
+/**
+ * Pack lines into as few mrkdwn section blocks as fit the 3000-char cap,
+ * preserving order. Long lists (a full service fleet, a file inventory)
+ * overflow a single section and make `chat.postMessage` refuse the whole
+ * card with `invalid_blocks`.
+ */
+export declare function mrkdwnSections(lines: readonly string[]): unknown[];
+export type SlackTableAlign = "left" | "center" | "right";
+export type SlackTableColumnSetting = {
+    align?: SlackTableAlign;
+    is_wrapped?: boolean;
+};
+/** Cell types accepted by Slack's native `table` block. */
+export type SlackTableCell = {
+    type: "raw_text";
+    text: string;
+} | {
+    type: "rich_text";
+    elements: Array<{
+        type: "rich_text_section";
+        elements: Array<{
+            type: "text";
+            text: string;
+        } | {
+            type: "link";
+            url: string;
+            text: string;
+        }>;
+    }>;
+};
+export type SlackTableBlock = {
+    type: "table";
+    rows: SlackTableCell[][];
+    column_settings?: SlackTableColumnSetting[];
+};
+/** Plain text cell (header or body). */
+export declare function slackRawTextCell(text: string): SlackTableCell;
+/** Linked cell via rich_text (preferred over mrkdwn `<url|label>` in tables). */
+export declare function slackLinkCell(args: {
+    url: string;
+    text: string;
+}): SlackTableCell;
+/**
+ * Build a native Slack `table` block. First row is the header. Slack allows
+ * at most one table block per message, 100 rows, and 20 columns — callers
+ * should keep tables short.
+ */
+export declare function slackTableBlock(args: {
+    headers: readonly string[];
+    rows: readonly (readonly SlackTableCell[])[];
+    columnSettings?: readonly SlackTableColumnSetting[];
+}): SlackTableBlock | undefined;
+//# sourceMappingURL=blocks.d.ts.map

package/dist/channels/slack/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/blocks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,EAAE,CA0BlE;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,mBAAmB,CAAC;QAC1B,QAAQ,EAAE,KAAK,CACb;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAC7E,CAAC;KACH,CAAC,CAAC;CACJ,CAAC;AAEN,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,cAAc,EAAE,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,uBAAuB,EAAE,CAAC;CAC7C,CAAC;AAEF,wCAAwC;AACxC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAE7D;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAUjF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,CAAC,SAAS,cAAc,EAAE,CAAC,EAAE,CAAC;IAC7C,cAAc,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACrD,GAAG,eAAe,GAAG,SAAS,CAgC9B"}

package/dist/channels/slack/blocks.js

@@ -0,0 +1,90 @@
+/**
+ * Block Kit building helpers shared by card-building agents.
+ */
+/** Slack cap for one section block's mrkdwn text. */
+export const SLACK_SECTION_MRKDWN_MAX = 3000;
+/** Slack caps for a native `table` block (one table per message). */
+export const SLACK_TABLE_MAX_ROWS = 100;
+export const SLACK_TABLE_MAX_COLUMNS = 20;
+/**
+ * Pack lines into as few mrkdwn section blocks as fit the 3000-char cap,
+ * preserving order. Long lists (a full service fleet, a file inventory)
+ * overflow a single section and make `chat.postMessage` refuse the whole
+ * card with `invalid_blocks`.
+ */
+export function mrkdwnSections(lines) {
+    const texts = [];
+    let current = "";
+    for (const raw of lines) {
+        // A single oversized line (one huge blob) hard-splits at the cap.
+        const parts = [];
+        for (let i = 0; i < Math.max(raw.length, 1); i += SLACK_SECTION_MRKDWN_MAX) {
+            parts.push(raw.slice(i, i + SLACK_SECTION_MRKDWN_MAX));
+        }
+        for (const line of parts) {
+            const next = current === "" ? line : `${current}\n${line}`;
+            if (next.length > SLACK_SECTION_MRKDWN_MAX && current !== "") {
+                texts.push(current);
+                current = line;
+            }
+            else {
+                current = next;
+            }
+        }
+    }
+    if (current !== "") {
+        texts.push(current);
+    }
+    return texts.map(text => ({
+        type: "section",
+        text: { type: "mrkdwn", text },
+    }));
+}
+/** Plain text cell (header or body). */
+export function slackRawTextCell(text) {
+    return { type: "raw_text", text };
+}
+/** Linked cell via rich_text (preferred over mrkdwn `<url|label>` in tables). */
+export function slackLinkCell(args) {
+    return {
+        type: "rich_text",
+        elements: [
+            {
+                type: "rich_text_section",
+                elements: [{ type: "link", url: args.url, text: args.text }],
+            },
+        ],
+    };
+}
+/**
+ * Build a native Slack `table` block. First row is the header. Slack allows
+ * at most one table block per message, 100 rows, and 20 columns — callers
+ * should keep tables short.
+ */
+export function slackTableBlock(args) {
+    if (args.headers.length === 0) {
+        return undefined;
+    }
+    if (args.headers.length > SLACK_TABLE_MAX_COLUMNS) {
+        throw new Error(`slackTableBlock: ${args.headers.length} columns exceeds Slack cap of ${SLACK_TABLE_MAX_COLUMNS}`);
+    }
+    // Header + body rows share the 100-row cap.
+    if (args.rows.length + 1 > SLACK_TABLE_MAX_ROWS) {
+        throw new Error(`slackTableBlock: ${args.rows.length + 1} rows exceeds Slack cap of ${SLACK_TABLE_MAX_ROWS}`);
+    }
+    const columnCount = args.headers.length;
+    for (const [index, row] of args.rows.entries()) {
+        if (row.length !== columnCount) {
+            throw new Error(`slackTableBlock: row ${index} has ${row.length} cells; expected ${columnCount}`);
+        }
+    }
+    const headerRow = args.headers.map(header => slackRawTextCell(header));
+    const block = {
+        type: "table",
+        rows: [headerRow, ...args.rows.map(row => [...row])],
+    };
+    if (args.columnSettings !== undefined && args.columnSettings.length > 0) {
+        block.column_settings = [...args.columnSettings];
+    }
+    return block;
+}

package/dist/channels/slack/bot-mentions.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 { type SlackLog } from "./log.js";
+import type { SlackBotMentionsOptions, SlackBotToken, SlackDelegationInfo, SlackMessage } from "./types.js";
+/** Slack message `metadata.event_type` for Agent SDK delegation posts. */
+export declare const SLACK_DELEGATION_METADATA_EVENT_TYPE = "agentkit_delegation";
+/** Default budgets for {@link SlackBotMentionsOptions}. */
+export declare const SLACK_BOT_MENTION_DEFAULTS: {
+    readonly maxDepth: 2;
+    readonly maxPerThreadPerHour: 5;
+    readonly maxPerThreadTotal: 20;
+};
+/**
+ * Parse delegation metadata off a raw Slack event (`event.metadata`).
+ * Returns undefined for absent, foreign, or malformed metadata.
+ */
+export declare function parseDelegationMetadata(event: unknown): SlackDelegationInfo | undefined;
+/** Build the Slack `metadata` body for an outbound delegation post. */
+export declare function buildDelegationMetadata(args: {
+    depth: number;
+    fromAgent?: string;
+    originSessionId?: string;
+}): Record<string, unknown>;
+/**
+ * Validate and normalize a `botMentions.allowFrom` list. Shared by channel
+ * construction (fail at definition time) and the gate (fail at start).
+ */
+export declare function normalizeBotMentionAllowlist(allowFrom: readonly string[]): string[];
+/**
+ * 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 declare function botMentionsFromEnv(envVar?: string): SlackBotMentionsOptions | undefined;
+export type SlackBotMentionVerdict = {
+    allow: true;
+    depth: number;
+} | {
+    allow: false;
+    reason: string;
+};
+/**
+ * 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 declare class SlackBotMentionGate {
+    private readonly identity;
+    private readonly allowFrom;
+    /** Compound entries: posting `bot_id` → allowed lowercase usernames. */
+    private readonly allowFromCompound;
+    private readonly maxDepth;
+    private readonly maxPerThreadPerHour;
+    private readonly maxPerThreadTotal;
+    private readonly windowMs;
+    private readonly threadBudgets;
+    private readonly log;
+    constructor(options: SlackBotMentionsOptions, identity: {
+        botUserId?: string;
+        botId?: string;
+    }, args?: {
+        log?: SlackLog;
+        windowMs?: number;
+    });
+    /**
+     * 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): SlackBotMentionVerdict;
+    private maybeEvictIdleThreads;
+}
+/**
+ * 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 declare 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;
+}>;
+//# sourceMappingURL=bot-mentions.d.ts.map

package/dist/channels/slack/bot-mentions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-mentions.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/bot-mentions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EACV,uBAAuB,EACvB,aAAa,EACb,mBAAmB,EACnB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,eAAO,MAAM,oCAAoC,wBAAwB,CAAC;AAE1E,2DAA2D;AAC3D,eAAO,MAAM,0BAA0B;aACrC,QAAQ,EAAE,CAAC;aACX,mBAAmB,EAAE,CAAC;aACtB,iBAAiB,EAAE,EAAE;CACb,CAAC;AAeX;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAyBvF;AAED,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAY1B;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAQnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,SAAkC,GACvC,uBAAuB,GAAG,SAAS,CAMrC;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAUrC;;;;;GAKG;AACH,qBAAa,mBAAmB;IAa5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAZ3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2B;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAW;IAE/B,YACE,OAAO,EAAE,uBAAuB,EACf,QAAQ,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EACjE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EA4B7C;IAED;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,GAAE,MAAmB,GAAG,sBAAsB,CAsElF;IAED,OAAO,CAAC,qBAAqB;CAU9B;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB1B"}

package/dist/channels/slack/bot-mentions.js

@@ -0,0 +1,257 @@
+/**
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { postMessage } from "./api.js";
+import { defaultSlackLog } from "./log.js";
+/** Slack message `metadata.event_type` for Agent SDK 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,
+};
+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) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+/**
+ * Parse delegation metadata off a raw Slack event (`event.metadata`).
+ * Returns undefined for absent, foreign, or malformed metadata.
+ */
+export function parseDelegationMetadata(event) {
+    const root = asRecord(event);
+    const metadata = asRecord(root === null || root === void 0 ? void 0 : 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 = { 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) {
+    const payload = { 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) {
+    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") {
+    var _a;
+    const allowFrom = ((_a = process.env[envVar]) !== null && _a !== void 0 ? _a : "")
+        .split(",")
+        .map(entry => entry.trim())
+        .filter(entry => entry !== "");
+    return allowFrom.length === 0 ? undefined : { allowFrom };
+}
+/**
+ * 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 {
+    constructor(options, identity, args) {
+        var _a, _b, _c, _d, _e, _f;
+        this.identity = identity;
+        this.threadBudgets = new Map();
+        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 = (_a = this.allowFromCompound.get(botId)) !== null && _a !== void 0 ? _a : new Set();
+            usernames.add(username);
+            this.allowFromCompound.set(botId, usernames);
+        }
+        this.maxDepth = (_b = options.maxDepth) !== null && _b !== void 0 ? _b : SLACK_BOT_MENTION_DEFAULTS.maxDepth;
+        this.maxPerThreadPerHour = (_c = options.maxPerThreadPerHour) !== null && _c !== void 0 ? _c : SLACK_BOT_MENTION_DEFAULTS.maxPerThreadPerHour;
+        this.maxPerThreadTotal = (_d = options.maxPerThreadTotal) !== null && _d !== void 0 ? _d : SLACK_BOT_MENTION_DEFAULTS.maxPerThreadTotal;
+        this.windowMs = (_e = args === null || args === void 0 ? void 0 : args.windowMs) !== null && _e !== void 0 ? _e : THREAD_BUDGET_WINDOW_MS;
+        this.log = (_f = args === null || args === void 0 ? void 0 : args.log) !== null && _f !== void 0 ? _f : 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, nowMs = Date.now()) {
+        var _a;
+        var _b, _c, _d;
+        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 = (_b = (_a = message.delegation) === null || _a === void 0 ? void 0 : _a.depth) !== null && _b !== void 0 ? _b : 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 = (_c = this.threadBudgets.get(key)) !== null && _c !== void 0 ? _c : {
+            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: (_d = author.botId) !== null && _d !== void 0 ? _d : author.userId,
+            depth,
+            thread_total: budget.total,
+        });
+        return { allow: true, depth };
+    }
+    maybeEvictIdleThreads(nowMs) {
+        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 function postDelegationMention(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const posted = yield 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: (_a = args.depth) !== null && _a !== void 0 ? _a : 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/dist/channels/slack/channel-watch.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Opt-in channel watch: dispatch on posts in allowlisted channels.
+ *
+ * Filtering rules (the anti-slop guarantees):
+ * - The allowlist is a finite id list, or a lone `"*"` for every channel
+ *   the bot is in. Mixing `"*"` with ids is a definition error.
+ * - Top-level posts only by default. `"replies"` is thread replies only
+ *   (`ts !== threadTs`). `"all"` is both. A lone `"*"` is replies only.
+ * - Posts that @mention the bot are skipped here (the `app_mention` path
+ *   owns them).
+ * - Bot-authored posts are dropped unless `includeBotPosts` is configured
+ *   (alert feeds / webhook integrations); the watching bot's own posts are
+ *   always dropped either way (loop safety).
+ * - An optional debounce window lets rapid edits settle: edits update the
+ *   pending text, deleting the post cancels the dispatch.
+ */
+import type { WebClient } from "@slack/web-api";
+import type { SlackChannelMessageEvent } from "./inbound.js";
+import { type SlackLog } from "./log.js";
+import type { SlackChannelPostsOptions, SlackMessage } from "./types.js";
+/**
+ * Channel-watch allowlist contract, mirrored by the control plane's
+ * deploy-time validation (proto posture: both sides validate
+ * independently). Ids are required because on Cursor-managed hosting they
+ * become channel-scoped subscription edges — the control plane drops
+ * channel posts outside the id set before any compute wakes, and it cannot
+ * resolve `#names`.
+ */
+export declare const CHANNEL_POSTS_MAX_CHANNEL_IDS = 10;
+/**
+ * True when the allowlist is only `"*"`: every channel the bot is in.
+ * Guest-side only. It is not a deploy-manifest subscription — the control
+ * plane rejects `"*"` and already delivers a reply in a thread a mention
+ * started. Top-level posts do not match it (`posts: "replies"`).
+ */
+export declare function channelPostsWatchEverywhere(entries: readonly string[]): boolean;
+/** The channel-id (`C…`/`G…`) entries of an allowlist, deduped. */
+export declare function channelPostIdEntries(entries: readonly string[]): string[];
+/**
+ * Validate `channelPosts.allow` at definition time. Returns an actionable
+ * error string (to be prefixed with the option path), or undefined.
+ */
+export declare function validateChannelPostsAllow(entries: readonly string[]): string | undefined;
+/** Allowlist over channel ids and `#names` (names resolve lazily). */
+export declare class SlackChannelAllowlist {
+    private readonly ids;
+    private readonly names;
+    private readonly everywhere;
+    constructor(entries: readonly string[]);
+    matches(channelId: string): boolean;
+    unresolvedNames(): string[];
+    /** Fold resolved `name → id` pairs into the id set. */
+    applyResolvedNames(resolved: ReadonlyMap<string, string>): void;
+}
+/**
+ * Resolve channel `#names` to ids via `conversations.list`. Best-effort:
+ * returns whatever resolved; the caller logs names that stayed unresolved.
+ */
+export declare function resolveChannelNames(client: WebClient, names: readonly string[], log?: SlackLog): Promise<Map<string, string>>;
+export interface ChannelPostWatcher {
+    /** Handle a parsed channel message event. Returns true when consumed. */
+    handle(event: SlackChannelMessageEvent, eventId?: string): boolean;
+    /** Cancel pending debounced dispatches. */
+    stop(): void;
+}
+export declare function createChannelPostWatcher(args: {
+    options: SlackChannelPostsOptions;
+    allowlist: SlackChannelAllowlist;
+    /** Bot user id (from `auth.test`) so bot mentions route via app_mention. */
+    getBotUserId: () => string | undefined;
+    /** This app's own `bot_id` (from `auth.test`) for self-post loop safety. */
+    getBotId?: () => string | undefined;
+    dispatch: (message: SlackMessage, eventId?: string) => void;
+    log?: SlackLog;
+}): ChannelPostWatcher;
+//# sourceMappingURL=channel-watch.d.ts.map

package/dist/channels/slack/channel-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-watch.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/channel-watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAG/E;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CASzE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAuBxF;AAED,sEAAsE;AACtE,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IAErC,YAAY,OAAO,EAAE,SAAS,MAAM,EAAE,EAqBrC;IAED,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAElC;IAED,eAAe,IAAI,MAAM,EAAE,CAE1B;IAED,uDAAuD;IACvD,kBAAkB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAO9D;CACF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,GAAG,GAAE,QAA0B,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAiC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,wBAAwB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnE,2CAA2C;IAC3C,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,wBAAwB,CAAC;IAClC,SAAS,EAAE,qBAAqB,CAAC;IACjC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB,GAAG,kBAAkB,CAwHrB"}