@cursor/july 0.1.54 → 0.1.61

package/dist/channels/origin/origin-webhook.d.ts

@@ -0,0 +1,38 @@
+export declare const V1ED_SIGNATURE_VERSION = "v1ed";
+export declare const DEFAULT_ORIGIN_API_BASE_URL = "https://origin.cursor.com";
+export type OriginJwk = Record<string, unknown>;
+export type OriginWebhookHeaders = {
+    "webhook-id"?: string;
+    "webhook-timestamp"?: string;
+    "webhook-signature"?: string;
+};
+export declare function buildV1edSignedContentDigest(args: {
+    webhookId: string;
+    timestampSeconds: number;
+    body: string | Buffer;
+}): string;
+/**
+ * Verify a delivery's Standard Webhooks headers against the Origin signing
+ * JWKS. Owns the whole check: header presence, timestamp parsing, the replay
+ * window, and Ed25519 verification against any provided key.
+ */
+export declare function verifyV1edWebhookPayload(args: {
+    publicJwks: readonly OriginJwk[];
+    body: string | Buffer;
+    headers: OriginWebhookHeaders;
+    nowMs?: number;
+}): boolean;
+/** Fetch (and cache for 5 minutes) the Origin signing JWKS. */
+export declare function fetchOriginJwks(apiBaseUrl: string, fetchImpl?: typeof fetch): Promise<readonly OriginJwk[]>;
+export interface VerifyOriginWebhookOptions {
+    apiBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    nowMs?: number;
+}
+/**
+ * Verify a Standard-Webhooks v1ed Origin payload. Throws on failure.
+ */
+export declare function verifyOriginWebhook(body: string | Buffer, headers: OriginWebhookHeaders, options?: VerifyOriginWebhookOptions): Promise<void>;
+/** Test helper: drop the in-process JWKS cache. */
+export declare function resetOriginWebhookKeysCache(): void;
+//# sourceMappingURL=origin-webhook.d.ts.map

package/dist/channels/origin/origin-webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin-webhook.d.ts","sourceRoot":"","sources":["../../../src/channels/origin/origin-webhook.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAC7C,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AAavE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB,GAAG,MAAM,CAUT;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CA6DV;AAMD,+DAA+D;AAC/D,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CA2B/B;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,mDAAmD;AACnD,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/channels/origin/origin-webhook.js

@@ -0,0 +1,151 @@
+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());
+    });
+};
+/**
+ * Origin webhook verification (Standard Webhooks `v1ed`).
+ *
+ * Direct Origin HTTP deliveries must verify the Ed25519 signature
+ * (`webhook-id`, `webhook-timestamp`, `webhook-signature`) against Origin's
+ * JWKS. Cursor-events relay deliveries skip this — the platform already
+ * verified the webhook before enqueueing.
+ *
+ * The signed content matches the Standard Webhooks `v1` scheme
+ * (`${webhook-id}.${webhook-timestamp}.${body}`) but is hashed to a lowercase
+ * hex SHA-256 before signing. Lifted from
+ * `factory/agentic-owners/agent/lib/origin-webhook.ts` /
+ * `backend/server/src/origin/webhooks/asymmetricWebhookSignature.ts`.
+ */
+import { createHash, createPublicKey, verify as verifyEd25519, } from "node:crypto";
+export const V1ED_SIGNATURE_VERSION = "v1ed";
+export const DEFAULT_ORIGIN_API_BASE_URL = "https://origin.cursor.com";
+/** ±5 minutes, the Standard Webhooks replay-window convention. */
+const V1ED_TIMESTAMP_TOLERANCE_SECONDS = 5 * 60;
+/**
+ * The sender emits exactly one v1ed entry; key rotation is handled by trying
+ * multiple public keys, never multiple signatures.
+ */
+const MAX_V1ED_CANDIDATE_SIGNATURES = 1;
+const JWKS_CACHE_TTL_MS = 5 * 60 * 1000;
+export function buildV1edSignedContentDigest(args) {
+    const prefix = Buffer.from(`${args.webhookId}.${args.timestampSeconds}.`, "utf8");
+    const body = typeof args.body === "string" ? Buffer.from(args.body, "utf8") : args.body;
+    return createHash("sha256")
+        .update(Buffer.concat([prefix, body]))
+        .digest("hex");
+}
+/**
+ * Verify a delivery's Standard Webhooks headers against the Origin signing
+ * JWKS. Owns the whole check: header presence, timestamp parsing, the replay
+ * window, and Ed25519 verification against any provided key.
+ */
+export function verifyV1edWebhookPayload(args) {
+    var _a;
+    const webhookId = args.headers["webhook-id"];
+    const webhookTimestamp = args.headers["webhook-timestamp"];
+    const signatureHeader = args.headers["webhook-signature"];
+    if (webhookId === undefined ||
+        webhookTimestamp === undefined ||
+        signatureHeader === undefined) {
+        return false;
+    }
+    const timestampSeconds = Number.parseInt(webhookTimestamp, 10);
+    if (Number.isNaN(timestampSeconds)) {
+        return false;
+    }
+    const nowSeconds = Math.floor(((_a = args.nowMs) !== null && _a !== void 0 ? _a : Date.now()) / 1000);
+    if (Math.abs(nowSeconds - timestampSeconds) > V1ED_TIMESTAMP_TOLERANCE_SECONDS) {
+        return false;
+    }
+    const digestBytes = Buffer.from(buildV1edSignedContentDigest({
+        webhookId,
+        timestampSeconds,
+        body: args.body,
+    }), "utf8");
+    const candidateSignatures = signatureHeader
+        .split(/\s+/)
+        .filter((entry) => entry.startsWith(`${V1ED_SIGNATURE_VERSION},`))
+        .map((entry) => entry.slice(V1ED_SIGNATURE_VERSION.length + 1))
+        .slice(0, MAX_V1ED_CANDIDATE_SIGNATURES);
+    if (candidateSignatures.length === 0) {
+        return false;
+    }
+    for (const jwk of args.publicJwks) {
+        let publicKey;
+        try {
+            publicKey = createPublicKey({
+                key: jwk,
+                format: "jwk",
+            });
+        }
+        catch (_b) {
+            continue;
+        }
+        for (const candidate of candidateSignatures) {
+            const signature = Buffer.from(candidate, "base64");
+            try {
+                if (verifyEd25519(null, digestBytes, publicKey, signature)) {
+                    return true;
+                }
+            }
+            catch (_c) {
+                // Malformed signature bytes or a non-Ed25519 key: try the next pair.
+            }
+        }
+    }
+    return false;
+}
+let jwksCache;
+/** Fetch (and cache for 5 minutes) the Origin signing JWKS. */
+export function fetchOriginJwks(apiBaseUrl_1) {
+    return __awaiter(this, arguments, void 0, function* (apiBaseUrl, fetchImpl = fetch) {
+        const now = Date.now();
+        if (jwksCache !== undefined &&
+            jwksCache.apiBaseUrl === apiBaseUrl &&
+            now - jwksCache.fetchedAtMs < JWKS_CACHE_TTL_MS) {
+            return jwksCache.keys;
+        }
+        const response = yield fetchImpl(`${apiBaseUrl.replace(/\/+$/, "")}/v1/origin/keys`);
+        if (!response.ok) {
+            throw new Error(`Origin JWKS fetch failed: status=${response.status}`);
+        }
+        const body = yield response.json().catch(() => undefined);
+        const keys = typeof body === "object" &&
+            body !== null &&
+            Array.isArray(body.keys)
+            ? body.keys
+            : [];
+        if (keys.length === 0) {
+            throw new Error("Origin JWKS fetch returned no keys");
+        }
+        jwksCache = { apiBaseUrl, keys, fetchedAtMs: now };
+        return keys;
+    });
+}
+/**
+ * Verify a Standard-Webhooks v1ed Origin payload. Throws on failure.
+ */
+export function verifyOriginWebhook(body, headers, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const apiBaseUrl = (_a = options === null || options === void 0 ? void 0 : options.apiBaseUrl) !== null && _a !== void 0 ? _a : DEFAULT_ORIGIN_API_BASE_URL;
+        const keys = yield fetchOriginJwks(apiBaseUrl, (_b = options === null || options === void 0 ? void 0 : options.fetchImpl) !== null && _b !== void 0 ? _b : fetch);
+        if (!verifyV1edWebhookPayload({
+            publicJwks: keys,
+            body,
+            headers,
+            nowMs: options === null || options === void 0 ? void 0 : options.nowMs,
+        })) {
+            throw new Error("Origin webhook signature verification failed");
+        }
+    });
+}
+/** Test helper: drop the in-process JWKS cache. */
+export function resetOriginWebhookKeysCache() {
+    jwksCache = undefined;
+}

package/dist/channels/origin/types.d.ts

@@ -0,0 +1,152 @@
+import type { AgentCloudOptions, ArtifactsApi, AuthContext, AuthPolicy, ChannelStartArgs, HostContext } from "../../types.js";
+export interface OriginActor {
+    id: string;
+    kind?: string;
+}
+export interface OriginRepositoryRef {
+    owner: string;
+    name: string;
+    fullName: string;
+}
+export interface OriginPullRequestEvent {
+    type: string;
+    number: number;
+    url: string;
+    title?: string;
+    body?: string | null;
+    draft?: boolean;
+    merged?: boolean;
+    authorId?: string;
+    headRef?: string;
+    headSha?: string;
+    baseRef?: string;
+    baseSha?: string;
+}
+export interface OriginComment {
+    id: string;
+    body: string;
+    author?: OriginActor;
+}
+export interface OriginReview {
+    id?: string;
+    verdict?: string;
+    author?: OriginActor;
+}
+export interface OriginEventContext {
+    deliveryId?: string;
+    eventType: string;
+    repository: OriginRepositoryRef;
+    pullRequestNumber: number;
+    pullRequestUrl: string;
+    sender?: OriginActor;
+    host: HostContext;
+    artifacts: ArtifactsApi;
+}
+export type OriginTurnDispatch = {
+    auth: AuthContext;
+    message?: string;
+    title?: string;
+    context?: readonly string[];
+};
+export type OriginTaskDispatch = {
+    task: () => Promise<void>;
+};
+export type OriginDispatch = OriginTurnDispatch | OriginTaskDispatch;
+export type OriginDispatchResult = OriginDispatch | null | Promise<OriginDispatch | null>;
+export type OriginPullRequestHook = (ctx: OriginEventContext, pullRequest: OriginPullRequestEvent) => OriginDispatchResult;
+export type OriginCommentHook = (ctx: OriginEventContext, comment: OriginComment) => OriginDispatchResult;
+export type OriginReviewHook = (ctx: OriginEventContext, review: OriginReview) => OriginDispatchResult;
+export type OriginEventHook = (ctx: OriginEventContext, event: {
+    eventType: string;
+    payload: unknown;
+}) => OriginDispatchResult;
+export type OriginCloudOptionsResolver = (ctx: OriginEventContext, pullRequest: OriginPullRequestEvent) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
+/**
+ * Origin delivery envelope. Public payloads are proto3 camelCase
+ * (`pullRequest`, `repository.owner.slug`).
+ */
+export interface OriginWebhookEnvelope {
+    deliveryId?: string;
+    appId?: string;
+    installationId?: string;
+    sender?: OriginActor;
+    event: {
+        id?: string;
+        type: string;
+        eventTime?: string;
+        payload?: unknown;
+    };
+}
+export interface OriginChannelOptions {
+    /**
+     * Use the signed-in Cursor account for inbound Origin events via
+     * `/v0/scm-events` (`provider: "origin"`). `true` takes repository scope
+     * from `serve --cursor-events --repo`; `{ repos }` makes the channel
+     * self-contained. Origin identity is the Cursor user — there is no
+     * separate OAuth principal, and this does not mint a GitHub token.
+     */
+    cursorAccount?: boolean | {
+        repos: readonly string[];
+    };
+    /**
+     * Origin app id this channel accepts (`envelope.appId`). v1ed only proves
+     * Origin signed the body with the platform JWKS; it does not bind the
+     * delivery to one app (any Origin app can aim signed POSTs at a public
+     * URL). Required for non-loopback HTTP, same role as GitHub's per-channel
+     * webhook secret. Falls back to `AGENT_SERVE_ORIGIN_APP_ID`.
+     */
+    appId?: string | readonly string[];
+    /**
+     * Optional Origin installation id bind (`envelope.installationId`). When
+     * set, HTTP deliveries for any other installation are rejected.
+     */
+    installationId?: string | readonly string[];
+    /**
+     * Optional HTTP/dispatch repo allowlist (`owner/name`). `{ cursorAccount:
+     * { repos } }` is also an allowlist. Events outside the set are acked
+     * without starting a turn. Omit to accept every repo the bound app sends.
+     */
+    repos?: readonly string[];
+    /**
+     * Route auth chain. Defaults to allow-all when {@link appId} (or
+     * `AGENT_SERVE_ORIGIN_APP_ID`) is set, because v1ed plus that app-id bind
+     * is the request auth. Without an app id, production stays loopback-strict
+     * (GitHub's no-secret posture); `--dev` / skip-verify admits loopback only.
+     */
+    auth?: AuthPolicy[];
+    /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
+    path?: string;
+    /** Origin API base used to fetch `/v1/origin/keys` for v1ed verify. */
+    apiBaseUrl?: string | (() => string | undefined);
+    /**
+     * Pin the Origin event types this channel dispatches on (published as
+     * `meta.originWebhookEvents`). Defaults to the set derived from hooks.
+     */
+    webhookEvents?: readonly string[];
+    /**
+     * Decide whether an inbound pull-request event starts a turn. Return
+     * `{ auth: defaultOriginAuth(ctx) }` to dispatch, `null` to ignore.
+     * Without this hook the channel dispatches on created / published /
+     * head_ref.pushed / base_ref.updated.
+     */
+    onPullRequest?: OriginPullRequestHook;
+    /** Opt-in `pull_request.comment.*` handler. No default dispatch. */
+    onComment?: OriginCommentHook;
+    /** Opt-in `pull_request.review.*` handler. No default dispatch. */
+    onReview?: OriginReviewHook;
+    /**
+     * Catch-all for Origin event types without a typed hook. NOT a fallback:
+     * events with a typed hook never reach this one.
+     */
+    onEvent?: OriginEventHook;
+    /**
+     * Per-session cloud options. Pass `true` to attach the PR repo using the
+     * pull request URL, or a resolver for custom cloud options.
+     */
+    cloud?: boolean | AgentCloudOptions | OriginCloudOptionsResolver;
+    /** Called once when the server mounts this channel. */
+    onStart?: (args: ChannelStartArgs) => void | Promise<void>;
+    /** Called when the server shuts down. */
+    onStop?: () => void | Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/channels/origin/types.d.ts.map

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

package/dist/channels/origin/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,6 +1,9 @@
 /**
- * Slack channel doctor — verify env, Socket Mode app token, auth.test.
+ * Slack channel doctor — verify env, Socket Mode app token, auth.test, and
+ * (when watched channels are supplied) that the bot token's workspace can
+ * actually see, join, and read those channels.
  */
+import { callSlackApi } from "./api.js";
 import type { SlackCredentials } from "./types.js";
 export interface SlackDoctorCheck {
     id: string;
@@ -14,11 +17,24 @@ export interface SlackDoctorResult {
         bot: string;
         app: string;
     };
+    /**
+     * Things a bot token cannot prove. Event subscriptions are app-level
+     * config, so a fully green doctor can still be a silent agent.
+     */
+    notes?: string[];
 }
 export interface SlackDoctorOptions {
     credentials?: SlackCredentials;
     /** Per-agent env prefix (e.g. `MY_AGENT`). */
     envPrefix?: string;
+    /**
+     * Watched channel ids (`engagement.channelPosts.allow`). Each is checked
+     * for visibility, bot membership, and history scope.
+     */
+    channels?: readonly string[];
+    /** Test seams. */
+    callImpl?: typeof callSlackApi;
+    fetchImpl?: typeof fetch;
 }
 export declare function runSlackDoctor(options?: SlackDoctorOptions): Promise<SlackDoctorResult>;
 //# sourceMappingURL=doctor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/doctor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,cAAc,CAClC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CA0G5B"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/doctor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAoC,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,kBAAkB;IAClB,QAAQ,CAAC,EAAE,OAAO,YAAY,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA4ID,wBAAsB,cAAc,CAClC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAsK5B"}

package/dist/channels/slack/doctor.js

@@ -1,5 +1,7 @@
 /**
- * Slack channel doctor — verify env, Socket Mode app token, auth.test.
+ * Slack channel doctor — verify env, Socket Mode app token, auth.test, and
+ * (when watched channels are supplied) that the bot token's workspace can
+ * actually see, join, and read those channels.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -12,17 +14,136 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { callSlackApi, resolveAppToken, resolveBotToken } from "./api.js";
 import { credentialsFromEnv, slackEnvKeys } from "./credentials.js";
+/**
+ * Socket Mode only delivers bot events the app subscribes to. Missing
+ * subscriptions produce total silence with valid tokens, and cannot be read
+ * back from a bot token.
+ */
+const REQUIRED_BOT_EVENTS = {
+    app_mention: "@mentions of the bot",
+    "message.im": "direct messages",
+    "message.channels": "public channel posts",
+    "message.groups": "private channel posts",
+    reaction_added: "reaction handlers (onReactionAdded)",
+};
+function eventSubscriptionNote() {
+    const lines = Object.entries(REQUIRED_BOT_EVENTS).map(([event, purpose]) => `    ${event} — ${purpose}`);
+    return [
+        "A bot token cannot read Event Subscriptions. If every check above passes",
+        "but the bot is silent, verify these bot events are subscribed on the app",
+        "(Slack app config -> Event Subscriptions -> Subscribe to bot events):",
+        ...lines,
+    ].join("\n");
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function errorOf(response) {
+    return typeof response.error === "string" ? response.error : "unknown";
+}
+/**
+ * Visibility, membership, and history-scope checks for one watched channel.
+ * `channel_not_found` here is the classic wrong-workspace bot token: the
+ * token authenticates fine, it just belongs to a different installation.
+ */
+function checkChannel(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { call, botToken, channelId } = args;
+        const checks = [];
+        let info;
+        try {
+            info = yield call({
+                botToken,
+                operation: "conversations.info",
+                body: { channel: channelId },
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: `channel_visible:${channelId}`,
+                ok: false,
+                message: `conversations.info threw: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            return checks;
+        }
+        if (info.ok !== true) {
+            const error = errorOf(info);
+            checks.push({
+                id: `channel_visible:${channelId}`,
+                ok: false,
+                message: error === "channel_not_found"
+                    ? `${channelId} not found by this bot token — the token is probably installed on a different workspace, or the channel id is wrong`
+                    : `conversations.info failed: ${error}`,
+            });
+            return checks;
+        }
+        const channel = asRecord(info.channel);
+        const name = typeof (channel === null || channel === void 0 ? void 0 : channel.name) === "string" ? channel.name : "?";
+        checks.push({
+            id: `channel_visible:${channelId}`,
+            ok: true,
+            message: `${channelId} visible (#${name})`,
+        });
+        const isMember = (channel === null || channel === void 0 ? void 0 : channel.is_member) === true;
+        checks.push({
+            id: `channel_member:${channelId}`,
+            ok: isMember,
+            message: isMember
+                ? `bot is a member of ${channelId}`
+                : `bot is NOT a member of ${channelId} — invite it to the channel`,
+        });
+        let history;
+        try {
+            history = yield call({
+                botToken,
+                operation: "conversations.history",
+                body: { channel: channelId, limit: 1 },
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: `channel_history:${channelId}`,
+                ok: false,
+                message: `conversations.history threw: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            return checks;
+        }
+        if (history.ok === true) {
+            checks.push({
+                id: `channel_history:${channelId}`,
+                ok: true,
+                message: `conversations.history ok for ${channelId}`,
+            });
+            return checks;
+        }
+        const error = errorOf(history);
+        const needed = typeof history.needed === "string" ? history.needed : undefined;
+        checks.push({
+            id: `channel_history:${channelId}`,
+            ok: false,
+            message: error === "missing_scope"
+                ? `conversations.history missing scope${needed === undefined ? "" : ` ${needed}`} — add it and reinstall the app`
+                : `conversations.history failed: ${error}`,
+        });
+        return checks;
+    });
+}
 export function runSlackDoctor() {
     return __awaiter(this, arguments, void 0, function* (options = {}) {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         const credentials = (_a = options.credentials) !== null && _a !== void 0 ? _a : credentialsFromEnv(options.envPrefix);
         const envKeys = slackEnvKeys(options.envPrefix);
         const checks = [];
+        const call = (_b = options.callImpl) !== null && _b !== void 0 ? _b : callSlackApi;
+        const fetchImpl = (_c = options.fetchImpl) !== null && _c !== void 0 ? _c : fetch;
         let appTokenRaw;
         try {
             appTokenRaw = yield resolveAppToken(credentials);
         }
-        catch (_f) {
+        catch (_k) {
             appTokenRaw = undefined;
         }
         const hasApp = appTokenRaw !== undefined && appTokenRaw !== "";
@@ -35,7 +156,7 @@ export function runSlackDoctor() {
         });
         if (hasApp && appTokenRaw !== undefined) {
             try {
-                const response = yield fetch("https://slack.com/api/apps.connections.open", {
+                const response = yield fetchImpl("https://slack.com/api/apps.connections.open", {
                     method: "POST",
                     headers: {
                         authorization: `Bearer ${appTokenRaw}`,
@@ -55,7 +176,7 @@ export function runSlackDoctor() {
                     checks.push({
                         id: "connections_open",
                         ok: false,
-                        message: `apps.connections.open failed: ${String((_b = data.error) !== null && _b !== void 0 ? _b : "unknown")}`,
+                        message: `apps.connections.open failed: ${String((_d = data.error) !== null && _d !== void 0 ? _d : "unknown")}`,
                     });
                 }
             }
@@ -71,7 +192,7 @@ export function runSlackDoctor() {
         try {
             botToken = yield resolveBotToken(credentials);
         }
-        catch (_g) {
+        catch (_l) {
             botToken = undefined;
         }
         const hasToken = botToken !== undefined && botToken !== "";
@@ -80,25 +201,31 @@ export function runSlackDoctor() {
             ok: hasToken,
             message: hasToken ? `${envKeys.bot} present` : `${envKeys.bot} is missing`,
         });
+        let authOk = false;
+        let botUserId = "";
         if (hasToken) {
             try {
-                const auth = yield callSlackApi({
+                const auth = yield call({
                     botToken,
                     operation: "auth.test",
                     body: {},
                 });
                 if (auth.ok === true) {
+                    authOk = true;
+                    botUserId = typeof auth.user_id === "string" ? auth.user_id : "";
                     checks.push({
                         id: "auth_test",
                         ok: true,
-                        message: `auth.test ok (team=${String((_c = auth.team) !== null && _c !== void 0 ? _c : "?")}, user=${String((_d = auth.user) !== null && _d !== void 0 ? _d : "?")})`,
+                        message: `auth.test ok (team=${String((_e = auth.team) !== null && _e !== void 0 ? _e : "?")}` +
+                            `, team_id=${String((_f = auth.team_id) !== null && _f !== void 0 ? _f : "?")}` +
+                            `, user=${String((_g = auth.user) !== null && _g !== void 0 ? _g : "?")})`,
                     });
                 }
                 else {
                     checks.push({
                         id: "auth_test",
                         ok: false,
-                        message: `auth.test failed: ${String((_e = auth.error) !== null && _e !== void 0 ? _e : "unknown")}`,
+                        message: `auth.test failed: ${String((_h = auth.error) !== null && _h !== void 0 ? _h : "unknown")}`,
                     });
                 }
             }
@@ -110,6 +237,55 @@ export function runSlackDoctor() {
                 });
             }
         }
-        return { ok: checks.every((check) => check.ok), checks, envKeys };
+        // The external-sender policy (`blockExternals`, on by default) classifies a
+        // sender as external whenever `users.info` fails — so a token that cannot
+        // look up users silently drops EVERY inbound event while all other checks
+        // stay green. Probe with the bot's own user id from auth.test.
+        if (authOk && botToken !== undefined && botUserId !== "") {
+            let info;
+            let threw;
+            try {
+                info = yield call({
+                    botToken,
+                    operation: "users.info",
+                    body: { user: botUserId },
+                });
+            }
+            catch (error) {
+                threw = error instanceof Error ? error.message : String(error);
+            }
+            if ((info === null || info === void 0 ? void 0 : info.ok) === true) {
+                checks.push({
+                    id: "users_read",
+                    ok: true,
+                    message: "users.info ok (users:read granted; external-sender policy can classify senders)",
+                });
+            }
+            else {
+                const error = threw !== null && threw !== void 0 ? threw : (info === undefined ? "unknown" : errorOf(info));
+                const hint = error === "missing_scope"
+                    ? "add the users:read scope and reinstall the app"
+                    : error === "user_not_found"
+                        ? "the token cannot see its own workspace's users — probably a token from a different installation"
+                        : "fix the token";
+                checks.push({
+                    id: "users_read",
+                    ok: false,
+                    message: `users.info failed: ${error} — ${hint}. The external-sender policy fails open to "external" on users.info errors, so every inbound event is silently dropped.`,
+                });
+            }
+        }
+        const channels = (_j = options.channels) !== null && _j !== void 0 ? _j : [];
+        if (authOk && botToken !== undefined && channels.length > 0) {
+            for (const channelId of channels) {
+                checks.push(...(yield checkChannel({ call, botToken, channelId })));
+            }
+        }
+        return {
+            ok: checks.every((check) => check.ok),
+            checks,
+            envKeys,
+            notes: [eventSubscriptionNote()],
+        };
     });
 }