@cursor/july 0.1.19 → 0.1.21

package/AGENTS.md

@@ -303,6 +303,16 @@ Fixtures still work for offline replay: `POST` a saved payload with an
   part of a code change. Docs are written intentionally, on explicit request
   only — never as a side effect of a feature or fix. If a change makes docs
   stale, say so in the PR description instead of editing them unprompted.
+- Grow an agent's deterministic path by default. Host code owns side-effect
+  gates and actuation, dedupe of external writes, auth, evidence seeding,
+  and hard API caps; formatting, summarizing, classification, and reply
+  composition stay with the model under an output contract in
+  `instructions.md` / skills (prose in `.md`, never TS string builders).
+  Speculative caches (prefetch, fingerprint dedupe, write coalescing) need
+  measured pressure first, and framework gaps (posting, chunking, retries)
+  get fixed or filed in the framework, not worked around in `agent/lib/`.
+  Budget + smells: `skills/create-agent/SKILL.md` § "The deterministic-path
+  budget".
 - Put durable `--state-root` inside a large monorepo if you care about
   ambient `AGENTS.md` / `.cursor` rules leaking into the agent workspace.
   Prefer `defineAgent({ local: { cwd } })` pointing outside the monorepo

package/dist/channels/github/instrument.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-request observability for GitHub channel Octokit clients.
+ *
+ * Every Octokit built by `createGitHubOctokit` / `callGitHubApi` gets one
+ * structured `[agentkit/github]` line per GitHub API request (REST and
+ * GraphQL), including rate-limit headers so installation-quota pressure can
+ * be attributed to agentkit deployments from hosted-runtime logs.
+ */
+import type { Octokit } from "@octokit/rest";
+export type GitHubRequestLogWrite = (line: string) => void;
+/** Best-effort GraphQL operation name (`query Foo` / `mutation Bar`). */
+export declare function parseGraphQLOperationName(query: unknown): string | undefined;
+/**
+ * Wrap an Octokit so every request emits one structured log line. Returns
+ * the same instance for call-through convenience. Idempotent per instance.
+ */
+export declare function instrumentGitHubOctokit(octokit: Octokit, input?: {
+    write?: GitHubRequestLogWrite;
+}): Octokit;
+//# sourceMappingURL=instrument.d.ts.map

package/dist/channels/github/instrument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../../../src/channels/github/instrument.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AA4C3D,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ5E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,KAAK,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAAE,GACxC,OAAO,CAmDT"}

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

@@ -90,6 +90,8 @@ export declare function postMessage(args: {
      * `markdown_text` hard-caps at 12k while `text` allows ~40k.
      */
     plainText?: boolean;
+    /** Slack message metadata (`{ event_type, event_payload }`). */
+    metadata?: Record<string, unknown>;
 }): Promise<{
     ts: string;
     channel: string;

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/api.ts"],"names":[],"mappings":"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"}

package/dist/channels/slack/api.js

@@ -261,6 +261,9 @@ export function postMessage(args) {
         if (args.threadTs !== undefined && args.threadTs !== "") {
             base.thread_ts = args.threadTs;
         }
+        if (args.metadata !== undefined) {
+            base.metadata = args.metadata;
+        }
         const hasBlocks = args.blocks !== undefined && args.blocks.length > 0;
         // User-group mentions (`<!subteam^…>`) and Slack mrkdwn links
         // (`<https://…|label>`) only render correctly via mrkdwn `text`,

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

@@ -0,0 +1,106 @@
+/**
+ * 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 agentkit 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;
+    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,yEAAyE;AACzE,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,CACrC,KAAK,EAAE,OAAO,GACb,mBAAmB,GAAG,SAAS,CA+BjC;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,CAC1C,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,EAAE,CAUV;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;IAW5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAV3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,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,EAgB7C;IAED;;;;OAIG;IACH,QAAQ,CACN,OAAO,EAAE,YAAY,EACrB,KAAK,GAAE,MAAmB,GACzB,sBAAsB,CAkExB;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,243 @@
+/**
+ * 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 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,
+};
+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;
+        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(normalizeBotMentionAllowlist(options.allowFrom));
+        this.maxDepth = (_a = options.maxDepth) !== null && _a !== void 0 ? _a : SLACK_BOT_MENTION_DEFAULTS.maxDepth;
+        this.maxPerThreadPerHour = (_b = options.maxPerThreadPerHour) !== null && _b !== void 0 ? _b : SLACK_BOT_MENTION_DEFAULTS.maxPerThreadPerHour;
+        this.maxPerThreadTotal = (_c = options.maxPerThreadTotal) !== null && _c !== void 0 ? _c : SLACK_BOT_MENTION_DEFAULTS.maxPerThreadTotal;
+        this.windowMs = (_d = args === null || args === void 0 ? void 0 : args.windowMs) !== null && _d !== void 0 ? _d : THREAD_BUDGET_WINDOW_MS;
+        this.log = (_e = args === null || args === void 0 ? void 0 : args.log) !== null && _e !== void 0 ? _e : 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 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 = (_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/dispatch.d.ts

@@ -2,6 +2,7 @@
  * Shared inbound dispatch for Slack Events API bodies and Socket Mode.
  */
 import type { HostContext, SendMessageFn } from "../../types.js";
+import type { SlackBotMentionGate } from "./bot-mentions.js";
 import type { ChannelPostWatcher } from "./channel-watch.js";
 import type { EventIdDedupe } from "./event-id-dedupe.js";
 import { type SlackLog } from "./log.js";
@@ -23,6 +24,11 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
     directMessagesEnabled?: boolean;
     /** Opt-in channel watch; absent = channel posts are ignored. */
     channelWatch?: ChannelPostWatcher;
+    /**
+     * Opt-in bot-to-bot mention gate; absent = bot-authored mentions are
+     * dropped at parse time (loop safety).
+     */
+    botMentionGate?: SlackBotMentionGate;
     /**
      * When false, skip the built-in `eval` directive. Defaults to true when
      * `host.evals` is present.

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/dispatch.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAa,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAK7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAO1D,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAM1D,OAAO,KAAK,EACV,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAEhB,YAAY,EACZ,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAIpB,uCAAuC;AACvC,wBAAgB,sBAAsB,CACpC,KAAK,GAAE,OAAO,CAAC,iBAAiB,CAAM,GACrC,iBAAiB,CAiBnB;AAED,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;IACvE,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC/C,YAAY,EAAE,mBAAmB,CAAC;IAClC,eAAe,EAAE,mBAAmB,CAAC;IACrC,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC1C,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,qDAAqD;IACrD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gEAAgE;IAChE,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAmBD,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,IAAI,EAAE,aAAa,GAAG,gBAAgB,GAAG,cAAc,GAAG,cAAc,CAAC;IACzE,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;IAClB,sBAAsB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,+BAA+B,CAAC,EAAE,CAChC,iBAAiB,EAAE,MAAM,KACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjC,qBAAqB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CA2QhB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CA0GT"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/dispatch.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAa,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAK7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAO1D,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAM1D,OAAO,KAAK,EACV,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAEhB,YAAY,EACZ,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAIpB,uCAAuC;AACvC,wBAAgB,sBAAsB,CACpC,KAAK,GAAE,OAAO,CAAC,iBAAiB,CAAM,GACrC,iBAAiB,CAiBnB;AAED,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;IACvE,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC/C,YAAY,EAAE,mBAAmB,CAAC;IAClC,eAAe,EAAE,mBAAmB,CAAC;IACrC,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC1C,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,qDAAqD;IACrD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gEAAgE;IAChE,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAmBD,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,IAAI,EAAE,aAAa,GAAG,gBAAgB,GAAG,cAAc,GAAG,cAAc,CAAC;IACzE,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;IAClB,sBAAsB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,+BAA+B,CAAC,EAAE,CAChC,iBAAiB,EAAE,MAAM,KACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjC,qBAAqB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CA2QhB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CA8HT"}

package/dist/channels/slack/dispatch.js

@@ -248,8 +248,9 @@ export function dispatchInboundMessage(args) {
  * true when a handler was scheduled.
  */
 export function dispatchInboundFromEventBody(body, deps) {
-    var _a;
-    const log = (_a = deps.log) !== null && _a !== void 0 ? _a : defaultSlackLog;
+    var _a, _b;
+    var _c, _d, _e;
+    const log = (_c = deps.log) !== null && _c !== void 0 ? _c : defaultSlackLog;
     let eventId;
     if (body !== null && typeof body === "object" && !Array.isArray(body)) {
         const root = body;
@@ -261,12 +262,32 @@ export function dispatchInboundFromEventBody(body, deps) {
             }
         }
     }
-    const mention = parseAppMentionEvent(body);
+    const mention = parseAppMentionEvent(body, {
+        includeBotAuthored: deps.botMentionGate !== undefined,
+    });
     if (mention !== null) {
         if (deps.mentionsEnabled === false) {
             log.debug("inbound ignored (mentions disabled)", { event_id: eventId });
             return false;
         }
+        if (((_a = mention.author) === null || _a === void 0 ? void 0 : _a.isBot) === true) {
+            // Parse only admits bot-authored mentions when a gate exists, so the
+            // fallback is defensive.
+            const verdict = (_d = (_b = deps.botMentionGate) === null || _b === void 0 ? void 0 : _b.evaluate(mention)) !== null && _d !== void 0 ? _d : {
+                allow: false,
+                reason: "bot mentions not enabled",
+            };
+            if (!verdict.allow) {
+                log.info("bot mention dropped", {
+                    event_id: eventId,
+                    channel: mention.channelId,
+                    thread_ts: mention.threadTs,
+                    from_bot: (_e = mention.author.botId) !== null && _e !== void 0 ? _e : mention.author.userId,
+                    reason: verdict.reason,
+                });
+                return false;
+            }
+        }
         deps.waitUntil(dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "app_mention", message: mention, handler: deps.onAppMention, send: deps.send, credentials: deps.credentials, host: deps.host, log, evalCommandsEnabled: deps.evalCommandsEnabled, cursorAgentName: deps.cursorAgentName }, (deps.hasContinuationSession === undefined
             ? {}
             : { hasContinuationSession: deps.hasContinuationSession })), (deps.isContinuationBusy === undefined

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

@@ -4,7 +4,16 @@
 import type { SlackMessage } from "./types.js";
 /** Strip common Slack mention tokens for a cleaner model prompt. */
 export declare function slackTextToMarkdown(text: string): string;
-export declare function parseAppMentionEvent(body: unknown): SlackMessage | null;
+export interface ParseAppMentionOptions {
+    /**
+     * Keep bot-authored mentions instead of dropping them at parse time.
+     * The dispatch layer enforces the per-channel policy
+     * ({@link SlackBotMentionsOptions}: allowlist, depth, thread budget)
+     * and always drops the agent's own posts.
+     */
+    includeBotAuthored?: boolean;
+}
+export declare function parseAppMentionEvent(body: unknown, options?: ParseAppMentionOptions): SlackMessage | null;
 /**
  * Parse DM / IM messages. More generous than a strict channel_type check:
  * accepts `channel_type === "im"` or channel ids starting with `D`, and

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

@@ -1 +1 @@
-{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/inbound.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,YAAY,CAAC;AAe5D,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASxD;AAoDD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAevE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CA8B1E;AAED,4EAA4E;AAC5E,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,0BAA0B,GACnC,wBAAwB,GAAG,IAAI,CA4DjC;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAYT"}
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/inbound.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,YAAY,CAAC;AAe5D,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASxD;AAoDD,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,sBAAsB,GAC/B,YAAY,GAAG,IAAI,CAsBrB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CA8B1E;AAED,4EAA4E;AAC5E,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,0BAA0B,GACnC,wBAAwB,GAAG,IAAI,CA4DjC;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAYT"}

package/dist/channels/slack/inbound.js

@@ -1,6 +1,7 @@
 /**
  * Parse Slack Events API payloads into structured inbound messages.
  */
+import { parseDelegationMetadata } from "./bot-mentions.js";
 import { slackApiMessageBody } from "./message-body.js";
 function asRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -53,7 +54,7 @@ function buildSlackMessage(event, teamId) {
         threadTs,
         channelId }, (teamId === undefined ? {} : { teamId })), (author === undefined ? {} : { author }));
 }
-export function parseAppMentionEvent(body) {
+export function parseAppMentionEvent(body, options) {
     const root = asRecord(body);
     if (root === null || root.type !== "event_callback") {
         return null;
@@ -62,12 +63,19 @@ export function parseAppMentionEvent(body) {
     if (event === null || event.type !== "app_mention") {
         return null;
     }
-    // Drop bot-authored mentions (mirrors DM filtering) to avoid loops.
+    // Drop bot-authored mentions (mirrors DM filtering) to avoid loops,
+    // unless the caller opted into the gated bot-mention path.
     const botId = asString(event.bot_id);
-    if (botId !== undefined && botId.length > 0) {
+    const isBotAuthored = botId !== undefined && botId.length > 0;
+    if (isBotAuthored && (options === null || options === void 0 ? void 0 : options.includeBotAuthored) !== true) {
         return null;
     }
-    return buildSlackMessage(event, asString(root.team_id));
+    const message = buildSlackMessage(event, asString(root.team_id));
+    if (message === null || !isBotAuthored) {
+        return message;
+    }
+    const delegation = parseDelegationMetadata(event);
+    return delegation === undefined ? message : Object.assign(Object.assign({}, message), { delegation });
 }
 /**
  * Parse DM / IM messages. More generous than a strict channel_type check:

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

@@ -22,6 +22,7 @@ export * from "./approvals.js";
 export * from "./assistant.js";
 export * from "./auth.js";
 export * from "./blocks.js";
+export * from "./bot-mentions.js";
 export * from "./channel-watch.js";
 export * from "./constants.js";
 export * from "./credentials.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC"}

package/dist/channels/slack/index.js

@@ -22,6 +22,7 @@ export * from "./approvals.js";
 export * from "./assistant.js";
 export * from "./auth.js";
 export * from "./blocks.js";
+export * from "./bot-mentions.js";
 export * from "./channel-watch.js";
 export * from "./constants.js";
 export * from "./credentials.js";

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

@@ -1 +1 @@
-{"version":3,"file":"slack-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/slack-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,iBAAiB,EAMlB,MAAM,gBAAgB,CAAC;AAyCxB,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAC7D,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAChD,SAAS,CAAC,EAAE,oBAAoB,CAAC,IAAI,CAAC,CAAC;CACnC,GACL,iBAAiB,CAAC,iBAAiB,CAAC,CAoatC"}
+{"version":3,"file":"slack-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/slack-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,iBAAiB,EAMlB,MAAM,gBAAgB,CAAC;AA8CxB,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAC7D,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAChD,SAAS,CAAC,EAAE,oBAAoB,CAAC,IAAI,CAAC,CAAC;CACnC,GACL,iBAAiB,CAAC,iBAAiB,CAAC,CAydtC"}