@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/feishu/process-registry.js

@@ -0,0 +1,90 @@
+/**
+ * Detect concurrent `bubble serve --feishu` instances for the same App ID.
+ *
+ * Two processes against the same App ID will fight over the long
+ * connection and double-process messages. We record the running PID + appId
+ * in `~/.bubble/feishu/processes.json` at startup and remove it at exit.
+ *
+ * On startup we check the file; any entry whose pid is still alive AND
+ * whose appId matches is a conflict.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { getProcessRegistryPath } from "./paths.js";
+export class ProcessRegistry {
+    file;
+    path;
+    constructor() {
+        this.path = getProcessRegistryPath();
+        this.file = this.read();
+    }
+    /** Return all entries whose pid is alive AND whose appId matches. */
+    findConflicts(appId) {
+        return this.file.processes
+            .filter((entry) => entry.appId === appId && isPidAlive(entry.pid))
+            .map((entry) => ({ entry }));
+    }
+    /** Kill any conflicting entry's process (SIGTERM). Returns count killed. */
+    killConflicts(appId) {
+        const conflicts = this.findConflicts(appId);
+        let killed = 0;
+        for (const c of conflicts) {
+            try {
+                process.kill(c.entry.pid, "SIGTERM");
+                killed++;
+            }
+            catch {
+                // process gone or no permission — fall through to next.
+            }
+        }
+        this.gc();
+        return killed;
+    }
+    /** Remove dead entries from disk. */
+    gc() {
+        this.file.processes = this.file.processes.filter((e) => isPidAlive(e.pid));
+        this.flush();
+    }
+    register(entry) {
+        // Replace any existing entry for this pid.
+        this.file.processes = this.file.processes.filter((e) => e.pid !== entry.pid);
+        this.file.processes.push(entry);
+        this.flush();
+    }
+    deregister(pid) {
+        this.file.processes = this.file.processes.filter((e) => e.pid !== pid);
+        this.flush();
+    }
+    read() {
+        if (!existsSync(this.path))
+            return { version: 1, processes: [] };
+        try {
+            const raw = readFileSync(this.path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.version !== 1 || !Array.isArray(parsed.processes)) {
+                return { version: 1, processes: [] };
+            }
+            return parsed;
+        }
+        catch {
+            return { version: 1, processes: [] };
+        }
+    }
+    flush() {
+        try {
+            writeFileSync(this.path, JSON.stringify(this.file, null, 2), { encoding: "utf8", mode: 0o600 });
+        }
+        catch {
+            // Best effort.
+        }
+    }
+}
+function isPidAlive(pid) {
+    try {
+        // Signal 0 doesn't deliver but checks existence.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/feishu/router/commands.d.ts

@@ -0,0 +1,38 @@
+/**
+ * In-chat slash-command parser and handlers.
+ *
+ * Commands run synchronously (no agent involvement) and reply with a plain
+ * text or markdown message. Admin commands silently no-op for non-admins
+ * (no error reply — that would expose the bot's existence).
+ */
+import type { BubbleChannel } from "../channel/channel.js";
+import type { ScopeRegistry } from "../scope/scope-registry.js";
+import type { SessionStore } from "../scope/session-store.js";
+import type { SessionBinder } from "../scope/session-binder.js";
+import type { ActiveRuns } from "../runtime/active-runs.js";
+import type { ScopeConfig, ScopeKey } from "../types.js";
+export interface CommandContext {
+    channel: BubbleChannel;
+    scopeRegistry: ScopeRegistry;
+    sessionStore: SessionStore;
+    sessionBinder: SessionBinder;
+    activeRuns: ActiveRuns;
+}
+export interface CommandInput {
+    chatId: string;
+    userId: string;
+    scope: ScopeConfig;
+    scopeKey: ScopeKey;
+    raw: string;
+    /** Reply target for ephemeral confirms. */
+    replyTo?: string;
+}
+export type CommandHandler = (input: CommandInput, args: string, ctx: CommandContext) => Promise<void>;
+export declare function isSlashCommand(text: string): boolean;
+/**
+ * Try to dispatch a slash command. Returns true if a command was matched
+ * and handled (regardless of success). Returns false if no command matched
+ * — caller should treat the message as a normal agent prompt.
+ */
+export declare function dispatchCommand(input: CommandInput, ctx: CommandContext): Promise<boolean>;
+export declare function listCommandNames(): string[];

package/dist/feishu/router/commands.js

@@ -0,0 +1,286 @@
+/**
+ * In-chat slash-command parser and handlers.
+ *
+ * Commands run synchronously (no agent involvement) and reply with a plain
+ * text or markdown message. Admin commands silently no-op for non-admins
+ * (no error reply — that would expose the bot's existence).
+ */
+import { resolve as resolvePath, isAbsolute as isAbsolutePath } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { formatPermissionMode, isPermissionModeName } from "../format.js";
+const COMMANDS = [];
+function register(def) {
+    COMMANDS.push(def);
+}
+export function isSlashCommand(text) {
+    const t = text.trim();
+    return t.startsWith("/") && !t.startsWith("//");
+}
+/**
+ * Try to dispatch a slash command. Returns true if a command was matched
+ * and handled (regardless of success). Returns false if no command matched
+ * — caller should treat the message as a normal agent prompt.
+ */
+export async function dispatchCommand(input, ctx) {
+    const t = input.raw.trim();
+    if (!isSlashCommand(t))
+        return false;
+    const space = t.indexOf(" ");
+    const head = (space === -1 ? t : t.slice(0, space)).toLowerCase();
+    const args = space === -1 ? "" : t.slice(space + 1).trim();
+    const def = COMMANDS.find((c) => `/${c.name}` === head);
+    if (!def) {
+        await ctx.channel.send(input.chatId, {
+            text: `未知命令 ${head}。发 /help 查看可用命令。`,
+        }, input.replyTo ? { replyTo: input.replyTo } : undefined);
+        return true;
+    }
+    if (def.adminOnly && !input.scope.admins.includes(input.userId)) {
+        // Silent drop for non-admins.
+        return true;
+    }
+    await def.handler(input, args, ctx);
+    return true;
+}
+// ---- /help ----
+register({
+    name: "help",
+    description: "列出可用命令",
+    adminOnly: false,
+    handler: async (input, _args, ctx) => {
+        const isAdmin = input.scope.admins.includes(input.userId);
+        const lines = ["**Bubble 飞书命令**"];
+        for (const c of COMMANDS) {
+            if (c.adminOnly && !isAdmin)
+                continue;
+            lines.push(`- \`/${c.name}\` — ${c.description}`);
+        }
+        await ctx.channel.send(input.chatId, { text: lines.join("\n") });
+    },
+});
+// ---- /status ----
+register({
+    name: "status",
+    description: "显示当前 scope / session / mode / 网络状态",
+    adminOnly: false,
+    handler: async (input, _args, ctx) => {
+        const entry = ctx.sessionStore.get(input.scopeKey);
+        const wsStatus = ctx.channel.getStatus();
+        const active = ctx.activeRuns.isActive(input.scopeKey);
+        const lines = [
+            `📁 cwd: \`${entry?.cwd ?? input.scope.cwd}\``,
+            `🛡 mode: \`${formatPermissionMode(entry?.permissionMode ?? input.scope.defaultPermissionMode)}\``,
+            `📄 session: \`${entry?.sessionFile ?? "(not yet started)"}\``,
+            `🔌 ws: \`${wsStatus?.state ?? "unknown"}\``,
+            `🤖 run: ${active ? "运行中" : "空闲"}`,
+        ];
+        await ctx.channel.send(input.chatId, { text: lines.join("\n") });
+    },
+});
+// ---- /cwd ----
+register({
+    name: "cwd",
+    description: "显示当前 cwd",
+    adminOnly: false,
+    handler: async (input, _args, ctx) => {
+        const entry = ctx.sessionStore.get(input.scopeKey);
+        const cwd = entry?.cwd ?? input.scope.cwd;
+        await ctx.channel.send(input.chatId, { text: `📁 \`${cwd}\`` });
+    },
+});
+// ---- /cd ----
+register({
+    name: "cd",
+    description: "切换到新目录并开新 session（绝对路径或 ~/...）",
+    adminOnly: false,
+    handler: async (input, args, ctx) => {
+        if (!args) {
+            await ctx.channel.send(input.chatId, { text: "用法：`/cd /absolute/path` 或 `/cd ~/projects/foo`" });
+            return;
+        }
+        const target = expandUser(args);
+        if (!isAbsolutePath(target)) {
+            await ctx.channel.send(input.chatId, { text: "❌ 路径必须是绝对路径或以 ~ 开头" });
+            return;
+        }
+        const resolved = resolvePath(target);
+        if (!existsSync(resolved)) {
+            await ctx.channel.send(input.chatId, { text: `❌ 路径不存在：\`${resolved}\`` });
+            return;
+        }
+        let isDir = false;
+        try {
+            isDir = statSync(resolved).isDirectory();
+        }
+        catch { /* */ }
+        if (!isDir) {
+            await ctx.channel.send(input.chatId, { text: `❌ 不是目录：\`${resolved}\`` });
+            return;
+        }
+        // Abort any in-flight run for this scope before swapping cwd.
+        ctx.activeRuns.abort(input.scopeKey);
+        const next = ctx.sessionBinder.changeCwd(input.scopeKey, resolved);
+        await ctx.channel.send(input.chatId, {
+            text: `✅ 已切换到 \`${next.cwd}\`，开新 session。`,
+        });
+    },
+});
+// ---- /mode ----
+register({
+    name: "mode",
+    description: "切换 permission mode（default / plan / bypassPermissions）",
+    adminOnly: false,
+    handler: async (input, args, ctx) => {
+        if (!args) {
+            const entry = ctx.sessionStore.get(input.scopeKey);
+            const current = entry?.permissionMode ?? input.scope.defaultPermissionMode;
+            await ctx.channel.send(input.chatId, {
+                text: `当前 mode: \`${formatPermissionMode(current)}\`\n用法：\`/mode <name>\` (default/plan/bypassPermissions)`,
+            });
+            return;
+        }
+        if (!isPermissionModeName(args)) {
+            await ctx.channel.send(input.chatId, {
+                text: `❌ 无效 mode \`${args}\`。可选：default / plan / bypassPermissions`,
+            });
+            return;
+        }
+        const mode = args;
+        // Ensure session entry exists so we have something to update.
+        const entry = ctx.sessionStore.get(input.scopeKey);
+        if (!entry) {
+            // Bootstrap session at fallback cwd, then set mode.
+            ctx.sessionBinder.openOrBootstrap(input.scopeKey, input.scope.cwd, mode);
+        }
+        else {
+            ctx.sessionStore.setPermissionMode(input.scopeKey, mode);
+        }
+        await ctx.channel.send(input.chatId, {
+            text: `🛡 mode 已切换为 \`${formatPermissionMode(mode)}\``,
+        });
+    },
+});
+// ---- /new ----
+register({
+    name: "new",
+    description: "归档当前 session，开始新对话",
+    adminOnly: false,
+    handler: async (input, _args, ctx) => {
+        ctx.activeRuns.abort(input.scopeKey);
+        const entry = ctx.sessionStore.get(input.scopeKey);
+        const cwd = entry?.cwd ?? input.scope.cwd;
+        const mode = entry?.permissionMode ?? input.scope.defaultPermissionMode;
+        ctx.sessionBinder.createFresh(input.scopeKey, cwd, mode);
+        await ctx.channel.send(input.chatId, { text: "✨ 已开新 session。" });
+    },
+});
+// ---- /resume ----
+register({
+    name: "resume",
+    description: "列出最近 session 让你选（不带参数）或恢复指定 session 名",
+    adminOnly: false,
+    handler: async (input, args, ctx) => {
+        const entry = ctx.sessionStore.get(input.scopeKey);
+        const cwd = entry?.cwd ?? input.scope.cwd;
+        if (!args) {
+            const recent = ctx.sessionBinder.listResumable(cwd, 10);
+            if (recent.length === 0) {
+                await ctx.channel.send(input.chatId, { text: "（这个目录下还没有 session 可恢复）" });
+                return;
+            }
+            const lines = ["最近 session：", ""];
+            for (const s of recent) {
+                const stamp = new Date(s.mtime).toISOString().slice(0, 19).replace("T", " ");
+                lines.push(`- \`${s.name}\` · ${stamp} · ${s.messageCount} msgs · ${s.title.slice(0, 50)}`);
+            }
+            lines.push("");
+            lines.push("用 `/resume <name>` 恢复。");
+            await ctx.channel.send(input.chatId, { text: lines.join("\n") });
+            return;
+        }
+        const recent = ctx.sessionBinder.listResumable(cwd, 50);
+        const match = recent.find((s) => s.name === args || s.file.endsWith(args));
+        if (!match) {
+            await ctx.channel.send(input.chatId, { text: `❌ 没找到 session \`${args}\`` });
+            return;
+        }
+        ctx.activeRuns.abort(input.scopeKey);
+        const opened = ctx.sessionBinder.resumeNamed(input.scopeKey, match.file);
+        if (!opened) {
+            await ctx.channel.send(input.chatId, { text: `❌ 恢复失败：\`${args}\`` });
+            return;
+        }
+        await ctx.channel.send(input.chatId, { text: `✅ 已恢复 \`${match.name}\` (cwd: ${opened.cwd})` });
+    },
+});
+// ---- /stop ----
+register({
+    name: "stop",
+    description: "中断当前运行",
+    adminOnly: false,
+    handler: async (input, _args, ctx) => {
+        const aborted = ctx.activeRuns.abort(input.scopeKey);
+        await ctx.channel.send(input.chatId, {
+            text: aborted ? "⏹ 已请求中断。" : "（当前没有正在运行的任务）",
+        });
+    },
+});
+// ---- /clear ----
+register({
+    name: "clear",
+    description: "在当前 session 里插入清除标记（保留历史文件，但后续对话不再带入旧上下文）",
+    adminOnly: false,
+    handler: async (input, _args, ctx) => {
+        const entry = ctx.sessionStore.get(input.scopeKey);
+        if (!entry) {
+            await ctx.channel.send(input.chatId, { text: "（还没有 session 可清除）" });
+            return;
+        }
+        const opened = ctx.sessionBinder.openOrBootstrap(input.scopeKey, entry.cwd, entry.permissionMode);
+        opened.manager.appendMarker("conversation_clear", String(Date.now()));
+        opened.manager.clearTitleMetadata();
+        await ctx.channel.send(input.chatId, { text: "🧹 已插入清除标记。下次发消息从空上下文开始。" });
+    },
+});
+// ---- /whoami ----
+register({
+    name: "whoami",
+    description: "显示你的 open_id",
+    adminOnly: false,
+    handler: async (input, _args, ctx) => {
+        const isAdmin = input.scope.admins.includes(input.userId) ? "（admin）" : "";
+        await ctx.channel.send(input.chatId, {
+            text: `👤 \`${input.userId}\` ${isAdmin}`,
+        });
+    },
+});
+// ---- /config ----
+register({
+    name: "config",
+    description: "[admin] 显示当前 scope 配置（只读）",
+    adminOnly: true,
+    handler: async (input, _args, ctx) => {
+        const lines = [
+            "**scope 配置：**",
+            `- chatId: \`${input.chatId}\``,
+            `- displayName: \`${input.scope.displayName}\``,
+            `- initial cwd: \`${input.scope.cwd}\``,
+            `- defaultPermissionMode: \`${formatPermissionMode(input.scope.defaultPermissionMode)}\``,
+            `- allowedUsers (${input.scope.allowedUsers.length}):`,
+            ...input.scope.allowedUsers.map((u) => `  - \`${u}\``),
+            `- admins (${input.scope.admins.length}):`,
+            ...input.scope.admins.map((u) => `  - \`${u}\``),
+        ];
+        await ctx.channel.send(input.chatId, { text: lines.join("\n") });
+    },
+});
+function expandUser(p) {
+    if (p === "~" || p.startsWith("~/")) {
+        return homedir() + p.slice(1);
+    }
+    return p;
+}
+export function listCommandNames() {
+    return COMMANDS.map((c) => c.name);
+}

package/dist/feishu/router/event-router.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Top-level inbound dispatcher.
+ *
+ * Wires `channel.onMessage` and `channel.onCardAction` to:
+ *   - run the three whitelist gates
+ *   - dispatch slash commands (sync, no agent)
+ *   - hand normal text to the PendingQueue (which eventually fires the
+ *     RunDriver via the flush callback)
+ *   - route cardAction events to the approval UI or stop-button handler
+ */
+import type { BubbleChannel } from "../channel/channel.js";
+import { type CommandContext } from "./commands.js";
+import type { ScopeRegistry } from "../scope/scope-registry.js";
+import type { SessionStore } from "../scope/session-store.js";
+import type { ActiveRuns } from "../runtime/active-runs.js";
+import type { PendingQueue } from "../runtime/pending-queue.js";
+import type { FeishuApprovalUI } from "../agent-host/approval-ui.js";
+import type { FeishuLogger } from "../logger.js";
+export interface EventRouterOptions {
+    channel: BubbleChannel;
+    scopeRegistry: ScopeRegistry;
+    sessionStore: SessionStore;
+    activeRuns: ActiveRuns;
+    pendingQueue: PendingQueue;
+    approvalUI: FeishuApprovalUI;
+    logger: FeishuLogger;
+    commandContext: CommandContext;
+    requireMentionInGroup: boolean;
+}
+export declare class EventRouter {
+    private readonly opts;
+    private unsubMessage?;
+    private unsubCardAction?;
+    private unsubReject?;
+    constructor(opts: EventRouterOptions);
+    start(): void;
+    stop(): void;
+    private handleMessage;
+    private handleCardAction;
+}

package/dist/feishu/router/event-router.js

@@ -0,0 +1,208 @@
+/**
+ * Top-level inbound dispatcher.
+ *
+ * Wires `channel.onMessage` and `channel.onCardAction` to:
+ *   - run the three whitelist gates
+ *   - dispatch slash commands (sync, no agent)
+ *   - hand normal text to the PendingQueue (which eventually fires the
+ *     RunDriver via the flush callback)
+ *   - route cardAction events to the approval UI or stop-button handler
+ */
+import { dispatchCommand, isSlashCommand } from "./commands.js";
+import { checkWhitelist } from "./whitelist.js";
+import { makeScopeKey } from "../types.js";
+export class EventRouter {
+    opts;
+    unsubMessage;
+    unsubCardAction;
+    unsubReject;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    start() {
+        this.unsubMessage = this.opts.channel.onMessage(async (msg) => {
+            this.opts.logger.info("message_received", {
+                phase: "router",
+                chatId: msg.chatId,
+                userId: msg.senderId,
+                messageId: msg.messageId,
+                chatType: msg.chatType,
+                contentType: msg.rawContentType,
+                mentionedBot: msg.mentionedBot,
+            });
+            try {
+                await this.handleMessage(msg);
+            }
+            catch (err) {
+                this.opts.logger.error("router_message_error", {
+                    phase: "router",
+                    chatId: msg.chatId,
+                    userId: msg.senderId,
+                    error: serializeError(err),
+                });
+            }
+        });
+        this.unsubCardAction = this.opts.channel.onCardAction(async (evt) => {
+            try {
+                await this.handleCardAction(evt);
+            }
+            catch (err) {
+                this.opts.logger.error("router_card_action_error", {
+                    phase: "router",
+                    chatId: evt.chatId,
+                    error: serializeError(err),
+                });
+            }
+        });
+        // Subscribe to SDK-level policy rejects so we can see if messages are
+        // being dropped before reaching our handler.
+        this.unsubReject = this.opts.channel.onReject((evt) => {
+            this.opts.logger.warn("sdk_reject", {
+                phase: "channel",
+                chatId: evt.chatId,
+                userId: evt.senderId,
+                messageId: evt.messageId,
+                reason: evt.reason,
+            });
+        });
+    }
+    stop() {
+        this.unsubMessage?.();
+        this.unsubCardAction?.();
+        this.unsubReject?.();
+    }
+    async handleMessage(msg) {
+        // Only text messages are processed in v1.
+        if (msg.rawContentType !== "text") {
+            this.opts.logger.debug("skip_non_text", {
+                phase: "router",
+                chatId: msg.chatId,
+                userId: msg.senderId,
+                kind: msg.rawContentType,
+            });
+            return;
+        }
+        // LarkChannel already normalizes text out of the raw `{"text":"..."}`
+        // JSON wrapper, so msg.content is the plain string we want.
+        const text = msg.content ?? "";
+        if (!text.trim()) {
+            this.opts.logger.debug("skip_empty_text", {
+                phase: "router",
+                chatId: msg.chatId,
+                userId: msg.senderId,
+            });
+            return;
+        }
+        const scope = this.opts.scopeRegistry.get(msg.chatId);
+        // Get chat mode from event (normalized to p2p/group; topic must be detected via getChatMode)
+        let chatMode = msg.chatType;
+        if (msg.chatType === "group") {
+            // Cheap check: if event already says group, fetch chat mode to detect topic.
+            try {
+                chatMode = await this.opts.channel.getChatMode(msg.chatId);
+            }
+            catch {
+                // Default to group if API call fails.
+                chatMode = "group";
+            }
+        }
+        const gate = checkWhitelist({
+            chatId: msg.chatId,
+            userId: msg.senderId,
+            chatType: chatMode,
+            mentionedBot: msg.mentionedBot,
+            scope,
+            requireMentionInGroup: this.opts.requireMentionInGroup,
+        });
+        if (!gate.ok) {
+            this.opts.logger.info("gate_rejected", {
+                phase: "router",
+                chatId: msg.chatId,
+                userId: msg.senderId,
+                reason: gate.reason,
+            });
+            // topic_chat is the one case where we DO reply, to help the user — they
+            // configured the chat but can't use it.
+            if (gate.reason === "topic_chat_unsupported") {
+                await this.opts.channel.send(msg.chatId, {
+                    text: "⚠️ 暂不支持话题群，请用普通群或私聊。",
+                });
+            }
+            return;
+        }
+        if (!scope)
+            return; // unreachable (gate.ok implies scope exists)
+        const scopeKey = makeScopeKey(msg.chatId, msg.senderId);
+        const cleanText = stripBotMention(text);
+        // Slash command?
+        if (isSlashCommand(cleanText)) {
+            await dispatchCommand({
+                chatId: msg.chatId,
+                userId: msg.senderId,
+                scope,
+                scopeKey,
+                raw: cleanText,
+                replyTo: msg.messageId,
+            }, this.opts.commandContext);
+            this.opts.scopeRegistry.touch(msg.chatId);
+            return;
+        }
+        // Normal agent prompt — push to queue.
+        this.opts.pendingQueue.push(scopeKey, {
+            text: cleanText,
+            messageId: msg.messageId,
+            receivedAt: Date.now(),
+        });
+        this.opts.scopeRegistry.touch(msg.chatId);
+    }
+    async handleCardAction(evt) {
+        const value = evt.action.value;
+        if (!value || typeof value !== "object")
+            return;
+        // Approval card button.
+        if (value.__bubble === "approval") {
+            await this.opts.approvalUI.dispatch({
+                cardMessageId: evt.messageId,
+                clickerOpenId: evt.operator.openId,
+                value,
+            });
+            return;
+        }
+        // Stop button on the run-state card.
+        if (value.__bubble === "stop_run") {
+            const scope = this.opts.scopeRegistry.get(evt.chatId);
+            if (!scope)
+                return;
+            if (!scope.allowedUsers.includes(evt.operator.openId))
+                return;
+            const scopeKey = makeScopeKey(evt.chatId, evt.operator.openId);
+            this.opts.activeRuns.abort(scopeKey);
+            this.opts.logger.info("stop_button_clicked", {
+                phase: "router",
+                chatId: evt.chatId,
+                userId: evt.operator.openId,
+            });
+            return;
+        }
+        // Unknown button — log and ignore.
+        this.opts.logger.debug("unknown_card_action", {
+            phase: "router",
+            chatId: evt.chatId,
+            value: JSON.stringify(value),
+        });
+    }
+}
+/**
+ * Strip leading `@_user_X` or `@bot` tokens that Feishu injects when the
+ * user @-mentions the bot. Specific tokens vary by tenant; a generic
+ * pattern handles the common cases.
+ */
+function stripBotMention(text) {
+    return text.replace(/^@[\w_]+\s+/g, "").trim();
+}
+function serializeError(err) {
+    if (err instanceof Error) {
+        return { message: err.message, name: err.name, stack: err.stack };
+    }
+    return { message: String(err) };
+}

package/dist/feishu/router/whitelist.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Three gates: scope (chat known?), user (in allowedUsers?), mention (group + requireMention?).
+ *
+ * Failed gates return reasons that the caller may log but should NOT reflect
+ * back to the user (silent drop) — surfacing the bot's existence is its own
+ * security exposure.
+ */
+import type { ScopeConfig } from "../types.js";
+export type WhitelistResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "scope_not_found" | "user_not_allowed" | "no_mention_in_group" | "topic_chat_unsupported";
+};
+export interface WhitelistCheckInput {
+    chatId: string;
+    userId: string;
+    chatType: "p2p" | "group" | "topic";
+    mentionedBot: boolean;
+    scope: ScopeConfig | undefined;
+    requireMentionInGroup: boolean;
+}
+export declare function checkWhitelist(input: WhitelistCheckInput): WhitelistResult;