botmux 3.7.1 → 3.8.0

package/dist/bot-registry.js

@@ -11,6 +11,21 @@ import { sanitizePerBotEnv } from './core/per-bot-env.js';
 import { normalizeSubstituteMode } from './services/substitute-mode-normalize.js';
 import { normalizePluginIdList } from './core/plugins/ids.js';
 import { normalizeVcMeetingProfileInstructions } from './services/vc-meeting-profile-instructions.js';
+/**
+ * Thrown when any Feishu client is requested for a core-only (`apiOnly`) bot.
+ * Defined here (the lowest-level module that owns bot config + client) so both
+ * `getBotClient` and higher layers (im/lark/client.ts primitives, doc-comment)
+ * throw the SAME typed error without an import cycle. apiOnly = zero Feishu
+ * network (reads AND writes); reaching a client request is genuine misuse.
+ */
+export class LarkTransportDisabledError extends Error {
+    constructor(larkAppId, op) {
+        super(`Feishu transport is disabled for core-only bot ${larkAppId} (attempted: ${op})`);
+        this.name = 'LarkTransportDisabledError';
+    }
+}
+/** Default when a bot sets nothing: usage rides the live streaming card. */
+export const DEFAULT_USAGE_DISPLAY = 'streaming';
 function normalizeChatReplyModeConfig(raw) {
     if (typeof raw !== 'string')
         return undefined;
@@ -37,6 +52,13 @@ function normalizeContentTriggerScope(raw) {
         return 'regularGroup';
     return undefined;
 }
+function normalizeMessageListenerSenderType(raw) {
+    if (raw === 'user' || raw === 'human')
+        return 'user';
+    if (raw === 'bot' || raw === 'app')
+        return 'bot';
+    return undefined;
+}
 function normalizeNonNegativeInt(raw) {
     if (typeof raw !== 'number')
         return undefined;
@@ -662,12 +684,88 @@ function normalizeContentTriggers(raw, botIndex) {
     });
     return out.length > 0 ? out : undefined;
 }
+function normalizeMessageListenerStringList(raw) {
+    const values = normalizeStringList(raw);
+    return values.length > 0 ? [...new Set(values)] : undefined;
+}
+function normalizeMessageListenerSenderTypes(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const values = raw
+        .map(normalizeMessageListenerSenderType)
+        .filter((value) => !!value);
+    return values.length > 0 ? [...new Set(values)] : undefined;
+}
+function normalizeMessageListenerConfig(raw, botIndex, chatId) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const entry = raw;
+    const prompt = normalizeNonEmptyString(entry.prompt);
+    const enabled = entry.enabled === true;
+    if (enabled && !prompt) {
+        logger.warn(`Bot config [${botIndex}] messageListeners[${chatId}] ignored: enabled listener requires prompt`);
+        return undefined;
+    }
+    const senderRaw = entry.senderPolicy && typeof entry.senderPolicy === 'object' && !Array.isArray(entry.senderPolicy)
+        ? entry.senderPolicy
+        : {};
+    const senderPolicy = {};
+    const mode = senderRaw.mode === 'include_only' ? 'include_only' : 'all_except_excluded';
+    const includeSenderOpenIds = normalizeMessageListenerStringList(senderRaw.includeSenderOpenIds);
+    const excludeSenderOpenIds = normalizeMessageListenerStringList(senderRaw.excludeSenderOpenIds);
+    const includeSenderTypes = normalizeMessageListenerSenderTypes(senderRaw.includeSenderTypes);
+    const excludeSenderTypes = normalizeMessageListenerSenderTypes(senderRaw.excludeSenderTypes);
+    if (mode !== 'all_except_excluded')
+        senderPolicy.mode = mode;
+    if (includeSenderOpenIds)
+        senderPolicy.includeSenderOpenIds = includeSenderOpenIds;
+    if (excludeSenderOpenIds)
+        senderPolicy.excludeSenderOpenIds = excludeSenderOpenIds;
+    if (includeSenderTypes)
+        senderPolicy.includeSenderTypes = includeSenderTypes;
+    if (excludeSenderTypes)
+        senderPolicy.excludeSenderTypes = excludeSenderTypes;
+    if (senderRaw.excludeSelf === false)
+        senderPolicy.excludeSelf = false;
+    const messageRaw = entry.messagePolicy && typeof entry.messagePolicy === 'object' && !Array.isArray(entry.messagePolicy)
+        ? entry.messagePolicy
+        : {};
+    const messagePolicy = {};
+    const includeMsgTypes = normalizeMessageListenerStringList(messageRaw.includeMsgTypes);
+    if (includeMsgTypes)
+        messagePolicy.includeMsgTypes = includeMsgTypes;
+    messagePolicy.scope = 'top_level';
+    return {
+        enabled,
+        ...(normalizeNonEmptyString(entry.name) ? { name: normalizeNonEmptyString(entry.name) } : {}),
+        ...(normalizeNonEmptyString(entry.replyCardTitle) ? { replyCardTitle: normalizeNonEmptyString(entry.replyCardTitle) } : {}),
+        ...(normalizeNonEmptyString(entry.workingDir) ? { workingDir: normalizeNonEmptyString(entry.workingDir) } : {}),
+        prompt: prompt ?? '',
+        ...(Object.keys(senderPolicy).length > 0 ? { senderPolicy } : {}),
+        ...(Object.keys(messagePolicy).length > 0 ? { messagePolicy } : {}),
+        replyPolicy: { mode: 'thread', sessionMode: 'per_message' },
+    };
+}
+function normalizeMessageListeners(raw, botIndex) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [chatId, listenerRaw] of Object.entries(raw)) {
+        if (typeof chatId !== 'string' || !chatId.trim())
+            continue;
+        const listener = normalizeMessageListenerConfig(listenerRaw, botIndex, chatId.trim());
+        if (listener)
+            out[chatId.trim()] = listener;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 const bots = new Map();
 export function __testOnly_resetBotRegistry() {
     bots.clear();
     loadedConfigPath = undefined;
     oncallChatCache = null;
     brandLabelCache = null;
+    usageDisplayCache = null;
 }
 // Wire the i18n lookup so `localeForBot()` can resolve per-bot locale without
 // a hard import cycle between `i18n` and `bot-registry`.
@@ -762,15 +860,45 @@ const larkLogger = {
     debug: (...msg) => logger.debug(`[lark] ${fmtLark(msg)}`),
     trace: (..._msg) => { },
 };
+/**
+ * Pure predicate: is this bot's VC-meeting-agent config ACTIVE (should the daemon
+ * attend meetings / restore VC runtime sessions / poll `lark-cli vc` for it)?
+ *
+ * Returns the config only when it is `enabled` AND the bot is NOT apiOnly. An
+ * apiOnly (core-only) bot has no Feishu connection — attending a VC meeting drives
+ * `lark-cli vc +meeting-events --as bot`, which categorically violates the
+ * zero-Feishu-network contract. Gating here (rather than only at each call site)
+ * means the daemon's central `effectiveVcMeetingAgentConfig` accessor — and every
+ * one of its ~24 consumers, including the boot-time `restoreVcMeetingRuntimeSessions`
+ * path that runs OUTSIDE the `!cfg.apiOnly` boot block — fail-closes for apiOnly by
+ * construction. The dashboard already refuses to SET an apiOnly listener; this also
+ * covers a hand-edited / migrated bots.json (a normal VC bot flipped to apiOnly with
+ * `vcMeetingAgent.enabled:true` + a stale on-disk runtime record).
+ */
+export function vcMeetingAgentConfigActive(cfg) {
+    if (!cfg)
+        return undefined;
+    if (cfg.apiOnly === true)
+        return undefined;
+    return cfg.vcMeetingAgent?.enabled === true ? cfg.vcMeetingAgent : undefined;
+}
 export function registerBot(cfg) {
-    const client = new Lark.Client({
-        appId: cfg.larkAppId,
-        appSecret: cfg.larkAppSecret,
-        // brand → SDK domain。缺省走 feishu，国际版租户走 larksuite.com。
-        // 这一行同时修好了所有经由 SDK 的调用（发消息 / 文件 / contact 等）。
-        domain: sdkDomain(normalizeBrand(cfg.brand)),
-        logger: larkLogger,
-    });
+    // apiOnly (core-only) bots have NO Feishu credential (empty appSecret). The Lark
+    // SDK Client ctor throws "appSecret or clientAssertionProvider is required" on an
+    // empty secret, so constructing it would fatal the whole daemon at boot — the
+    // exact failure riff hit in a clean sandbox. An apiOnly bot never uses the client
+    // (getBotClient throws LarkTransportDisabledError first; getAllBotClients filters
+    // apiOnly), so leave it null. Zero Feishu transport is the whole contract.
+    const client = cfg.apiOnly === true
+        ? null
+        : new Lark.Client({
+            appId: cfg.larkAppId,
+            appSecret: cfg.larkAppSecret,
+            // brand → SDK domain。缺省走 feishu，国际版租户走 larksuite.com。
+            // 这一行同时修好了所有经由 SDK 的调用（发消息 / 文件 / contact 等）。
+            domain: sdkDomain(normalizeBrand(cfg.brand)),
+            logger: larkLogger,
+        });
     const state = {
         config: cfg,
         client,
@@ -794,7 +922,25 @@ export function getBot(larkAppId) {
     return state;
 }
 export function getBotClient(larkAppId) {
-    return getBot(larkAppId).client;
+    const bot = getBot(larkAppId);
+    // Bot-level transport boundary at the TRUE shared base. `apiOnly` (core-only)
+    // means zero Feishu network — reads AND writes — not merely "no sends". Every
+    // Feishu call in the codebase resolves its client here (client.ts primitives,
+    // doc-comment drive API, open-platform rename/avatar, identity cache…), so
+    // throwing here is the single authoritative gate no caller can bypass. A
+    // correctly-built apiOnly flow never reaches this (session/CLI gates fire
+    // first); reaching it is genuine misuse and must fail loud, not silently.
+    if (bot.config.apiOnly === true) {
+        throw new LarkTransportDisabledError(larkAppId, 'getBotClient');
+    }
+    // Non-apiOnly bots always have a constructed client (registerBot builds one for
+    // every non-apiOnly config). The null-guard is defensive — a null here would mean
+    // a misconfigured bot slipped the apiOnly gate, which must fail loud, not NPE deep
+    // in an SDK call.
+    if (!bot.client) {
+        throw new Error(`Bot ${larkAppId} has no Lark client (apiOnly misconfiguration)`);
+    }
+    return bot.client;
 }
 /** Owner = bot 首个已授权 open_id，与「缺权限警告私信对象」同口径（见 admin 解析）。 */
 export function getOwnerOpenId(larkAppId) {
@@ -941,6 +1087,20 @@ export function isChatOncallBoundForAnyBot(chatId) {
 // Per-bot brand label, mtime-cached for the disk fallback. Keyed by larkAppId →
 // the configured value (undefined when the bot has no brandLabel key).
 let brandLabelCache = null;
+let usageDisplayCache = null;
+/** Normalize a raw bots.json entry's usage-display intent to the enum, applying
+ *  backward compat: an explicit `usageDisplay` wins; otherwise a legacy
+ *  `showUsageInCardFooter: false` maps to `'off'`; everything else is the
+ *  default (`'streaming'`). Single source of truth for both the in-memory parse
+ *  and the disk-fallback resolver so they cannot drift. */
+export function normalizeUsageDisplay(entry) {
+    if (entry.usageDisplay === 'streaming' || entry.usageDisplay === 'footer' || entry.usageDisplay === 'off') {
+        return entry.usageDisplay;
+    }
+    if (entry.showUsageInCardFooter === false)
+        return 'off';
+    return DEFAULT_USAGE_DISPLAY;
+}
 /** Resolve the bots.json path the same way loadBotConfigs does, without
  *  requiring the registry to have been loaded (works in one-shot CLI processes
  *  like `botmux send`). Returns null when no config file exists. */
@@ -996,6 +1156,46 @@ export function resolveBrandLabel(larkAppId) {
         return undefined;
     }
 }
+/**
+ * Resolve the per-bot usage-display mode (default `'streaming'`). A freshly
+ * loaded registry wins over the spawn-time env so long-lived panes observe
+ * `/botconfig` hot updates; sandboxed/env-only processes carry the value in
+ * their synthetic registered bot and otherwise fall back to the injected env.
+ */
+export function resolveUsageDisplay(larkAppId) {
+    const inMem = bots.get(larkAppId);
+    if (inMem)
+        return normalizeUsageDisplay(inMem.config);
+    if (process.env.BOTMUX_LARK_APP_ID === larkAppId
+        && 'BOTMUX_USAGE_DISPLAY' in process.env) {
+        const env = process.env.BOTMUX_USAGE_DISPLAY;
+        if (env === 'streaming' || env === 'footer' || env === 'off')
+            return env;
+        return DEFAULT_USAGE_DISPLAY;
+    }
+    const path = loadedConfigPath ?? botsConfigDiskPath();
+    if (!path)
+        return DEFAULT_USAGE_DISPLAY;
+    try {
+        const stat = statSync(path);
+        if (!usageDisplayCache || usageDisplayCache.mtimeMs !== stat.mtimeMs) {
+            const raw = JSON.parse(readFileSync(path, 'utf-8'));
+            const map = new Map();
+            if (Array.isArray(raw)) {
+                for (const entry of raw) {
+                    if (entry && typeof entry.larkAppId === 'string') {
+                        map.set(entry.larkAppId, normalizeUsageDisplay(entry));
+                    }
+                }
+            }
+            usageDisplayCache = { mtimeMs: stat.mtimeMs, map };
+        }
+        return usageDisplayCache.map.get(larkAppId) ?? DEFAULT_USAGE_DISPLAY;
+    }
+    catch {
+        return DEFAULT_USAGE_DISPLAY;
+    }
+}
 /**
  * 只读 accessor：该 bot 配置的 tuiSlashAllow allowlist（TUI 通用 slash 注入用）。
  * 仅读内存态注册表，daemon 进程内使用；无需 bots.json 磁盘回退（不同于
@@ -1008,10 +1208,55 @@ export function getBotTuiSlashAllow(larkAppId) {
  * Load bot configurations from one of (in priority order):
  * 1. BOTS_CONFIG env var — path to a JSON file
  * 2. ~/.botmux/bots.json — default config path
+ * 3. Core-only (BOTMUX_CORE_ONLY=1) with NEITHER of the above present:
+ *    synthesize a single apiOnly bot from env — no bots.json / no Feishu creds
+ *    (riff's in-sandbox headless service).
  */
 export function loadBotConfigs() {
+    const synthetic = maybeSynthesizeCoreOnlyConfig();
+    if (synthetic)
+        return synthetic;
     return parseBotConfigFile(resolveBotConfigPath());
 }
+/**
+ * Core-only headless config: when BOTMUX_CORE_ONLY=1, synthesize ONE apiOnly bot
+ * from env so the daemon boots with zero Feishu credentials and no on-disk config.
+ *
+ * Core-only is AUTHORITATIVE about identity and IGNORES all ambient config inputs
+ * — both ~/.botmux/bots.json AND the BOTS_CONFIG env (codex P1-2). Otherwise a
+ * core-only service started on a host that happens to have a real fleet config —
+ * or with an inherited/leaked BOTS_CONFIG — would silently boot a REAL,
+ * transport-enabled Feishu bot (WSClient, real credentials, `--bot` ignored)
+ * instead of the headless apiOnly one, the exact opposite of "no Feishu". There
+ * is deliberately NO file-based override in this mode: the identity is exactly the
+ * one synthesized here (frozen: apiOnly, `local_<slug>`, no secret). Returns null
+ * only when not in core-only mode.
+ *
+ * The synthesized `loadedConfigPath` is pinned to the DEFAULT ~/.botmux/bots.json
+ * path (even though the file is absent/ignored) so the no-transport fs-policy sees
+ * the config as living INSIDE the default botmux authority root — never an external
+ * path or a carve-out, which would trip buildFsPolicy's fail-closed checks.
+ */
+function maybeSynthesizeCoreOnlyConfig() {
+    if (process.env.BOTMUX_CORE_ONLY !== '1')
+        return null;
+    const larkAppId = process.env.BOTMUX_API_ONLY_BOT || 'local_riff';
+    if (!/^local_[A-Za-z0-9._-]+$/.test(larkAppId)) {
+        throw new Error(`Core-only BOTMUX_API_ONLY_BOT must match local_<slug> (letters/digits/._-), got: ${larkAppId}`);
+    }
+    const cliId = process.env.BOTMUX_CORE_CLI || 'codex-app';
+    const entry = { larkAppId, apiOnly: true, cliId };
+    if (process.env.BOTMUX_CORE_WORKING_DIR)
+        entry.workingDir = process.env.BOTMUX_CORE_WORKING_DIR;
+    if (process.env.BOTMUX_CORE_MODEL)
+        entry.model = process.env.BOTMUX_CORE_MODEL;
+    // Route through the normal parser so the synthesized entry gets identical
+    // validation + normalization as a file-loaded one (apiOnly secret exemption,
+    // cliId check, defaults). Pin loadedConfigPath to the default in-root path.
+    const configs = parseBotConfigsFromText(JSON.stringify([entry]));
+    loadedConfigPath = resolve(homedir(), '.botmux', 'bots.json');
+    return configs;
+}
 function resolveBotConfigPath() {
     // 1. BOTS_CONFIG env var
     const botsConfigPath = process.env.BOTS_CONFIG;
@@ -1163,7 +1408,19 @@ export function parseBotConfigsFromText(jsonText) {
         if (!entry.larkAppId || typeof entry.larkAppId !== 'string') {
             throw new Error(`Bot config [${i}]: larkAppId is required and must be a string`);
         }
-        if (!entry.larkAppSecret || typeof entry.larkAppSecret !== 'string') {
+        // apiOnly (core-only) bots drive purely over the HTTP control API and never
+        // connect to Feishu, so a real app secret is not required. larkAppId is still
+        // mandatory (daemon identity + dashboard routing + cachedLarkAppId gate); use
+        // a synthetic local id like `local_<slug>`. Normal Feishu bots keep the hard
+        // requirement — a missing secret there is a misconfig, not a headless bot.
+        // The rule for apiOnly is "may be omitted; if present it must still be a
+        // string" — a number/object/array/false must NOT slip into a string field.
+        if (entry.apiOnly === true) {
+            if (entry.larkAppSecret !== undefined && typeof entry.larkAppSecret !== 'string') {
+                throw new Error(`Bot config [${i}]: larkAppSecret must be a string when provided (apiOnly bots may omit it)`);
+            }
+        }
+        else if (!entry.larkAppSecret || typeof entry.larkAppSecret !== 'string') {
             throw new Error(`Bot config [${i}]: larkAppSecret is required and must be a string`);
         }
         // MOSA-managed onboarding persists the exact App/secret/owner binding so
@@ -1257,7 +1514,7 @@ export function parseBotConfigsFromText(jsonText) {
             if (ids.length > 0)
                 globalGrants = ids;
         }
-        // messageQuota.defaultLimit：仅保留正整数；非法/缺省 → undefined（= 默认额度关闭）。
+        // messageQuota.defaultLimit：仅保留正整数；非法/缺省 → undefined（卡片用产品默认 3 条）。
         let messageQuota;
         const rawMq = entry.messageQuota;
         if (rawMq && typeof rawMq === 'object' && !Array.isArray(rawMq)) {
@@ -1285,6 +1542,22 @@ export function parseBotConfigsFromText(jsonText) {
             if (Object.keys(out).length > 0)
                 quotaState = out;
         }
+        let grantExpiryState;
+        if (entry.grantExpiryState && typeof entry.grantExpiryState === 'object' && !Array.isArray(entry.grantExpiryState)) {
+            const out = {};
+            for (const [k, v] of Object.entries(entry.grantExpiryState)) {
+                if (!/^(chat:.+:.+|global:.+)$/.test(k))
+                    continue;
+                if (!v || typeof v !== 'object')
+                    continue;
+                const expiresAt = v.expiresAt;
+                if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt) || expiresAt <= 0)
+                    continue;
+                out[k] = { expiresAt };
+            }
+            if (Object.keys(out).length > 0)
+                grantExpiryState = out;
+        }
         // customPassthroughCommands：用户额外放行透传的 slash 命令。归一化：转小写、
         // 自动补前导 `/`、按 /^\/[a-z0-9][a-z0-9:_-]*$/ 过滤、去重。非法/缺省 → undefined。
         // 注意：与 daemon 命令的冲突过滤放在 resolvePassthroughCommands（运行时合并）做，
@@ -1353,6 +1626,7 @@ export function parseBotConfigsFromText(jsonText) {
             : undefined;
         const summaryRange = normalizeSummaryRange(entry.summaryRange ?? entry.summary);
         const contentTriggers = normalizeContentTriggers(entry.contentTriggers, i);
+        const messageListeners = normalizeMessageListeners(entry.messageListeners, i);
         const vcMeetingAgent = normalizeVcMeetingAgentConfig(entry.vcMeetingAgent);
         // voice：per-bot 语音引擎覆盖。结构化保留（engine ∈ sami|openai，sami/openai
         // 为对象，speaker/rate 透传）；非对象或 engine 非法 → undefined。深度校验
@@ -1381,7 +1655,11 @@ export function parseBotConfigsFromText(jsonText) {
         }
         configs.push({
             larkAppId: entry.larkAppId,
-            larkAppSecret: entry.larkAppSecret,
+            // apiOnly bots may omit the secret (never used — no Feishu connection);
+            // fall back to '' so downstream env plumbing stays a string. Feishu image
+            // upload etc. already degrade gracefully on an empty secret.
+            larkAppSecret: entry.larkAppSecret ?? '',
+            apiOnly: entry.apiOnly === true || undefined,
             // brand：只认精确的 'lark'，其余 → undefined（下游 normalizeBrand 当
             // feishu）。feishu 故意存成 undefined，保持旧 bots.json 干净、不写死字段。
             brand: entry.brand === 'lark' ? 'lark' : undefined,
@@ -1450,6 +1728,7 @@ export function parseBotConfigsFromText(jsonText) {
             p2pOpen: entry.p2pOpen === true || undefined,
             messageQuota,
             quotaState,
+            grantExpiryState,
             restrictGrantCommands: entry.restrictGrantCommands === true || undefined,
             // Default is ON, so only explicit false is meaningful/persisted.
             autoGrantRequestCards: entry.autoGrantRequestCards === false ? false : undefined,
@@ -1466,6 +1745,12 @@ export function parseBotConfigsFromText(jsonText) {
             // Preserve '' distinctly from undefined: '' means "brand off", undefined
             // means "use default botmux brand". Don't trim-to-undefined here.
             brandLabel: typeof entry.brandLabel === 'string' ? entry.brandLabel : undefined,
+            // Persist only a non-default usage-display mode; 'streaming' (default) and
+            // an absent key both mean streaming. Legacy showUsageInCardFooter:false is
+            // still honored on read (see normalizeUsageDisplay) but never re-emitted.
+            usageDisplay: normalizeUsageDisplay(entry) === DEFAULT_USAGE_DISPLAY
+                ? undefined
+                : normalizeUsageDisplay(entry),
             disableStreamingCard: entry.disableStreamingCard === true || undefined,
             silentTurnReactions: entry.silentTurnReactions === true || undefined,
             receivedReactionEmoji: typeof entry.receivedReactionEmoji === 'string' && entry.receivedReactionEmoji.trim()
@@ -1492,6 +1777,7 @@ export function parseBotConfigsFromText(jsonText) {
                 ? entry.autoStartOnGroupJoinPrompt
                 : undefined,
             autoStartOnNewTopic: entry.autoStartOnNewTopic === true || undefined,
+            messageListeners,
             worktreeMultiPicker: entry.worktreeMultiPicker === true || undefined,
             // Per-bot regular-group default mode. Default is 'chat-topic' (顶层平铺
             // 连续会话；群内原生话题各自独立会话), so only the NON-default modes