evolcore 0.0.3 → 0.0.4

package/dist/core/message/message-bridge.js

@@ -2,40 +2,63 @@ import { createHash, randomBytes } from 'crypto';
 import { logger } from '../../utils/logger.js';
 import { StreamDebouncer } from './stream-debouncer.js';
 import { appendMessageLog, appendMessageLogStrict, buildInboundEntry, isTransientProtocolMessage } from './message-log.js';
-import { buildEnvelope } from './message-utils.js';
+import { buildEnvelope, sendInteractionPayload } from './message-utils.js';
 import { chatDirPath } from '../session/session-fs-store.js';
-import { tryParseChannelKey } from '../channel-loader.js';
+import { formatChannelKey, tryParseChannelKey } from '../channel-loader.js';
 import { agentDir, resolvePaths } from '../../paths.js';
-import { resolvePeerRoleDetail } from '../../config/peer-role-resolver.js';
-import { isBlockedContact, resolveContactView } from '../../config/contact-book.js';
+import { listStaticAgentAdmins, listStaticAgentOwners, resolvePeerRoleDetail, } from '../../config/peer-role-resolver.js';
+import { resolveContactView, resolvePeerDisplayLabel, resolvePrincipal } from '../../config/contact-book.js';
+import { findContactRequestNote, expirePendingContactRequests, reviewContactRequest, submitContactRequest, } from '../../config/contact-request-service.js';
 import { isValidAid } from '../../aun/aid/validation.js';
 import { PeerIdentityCache } from '../relation/peer-identity.js';
-import { handlePendingDingtalkContactBindMessage } from '../../channels/dingtalk.js';
-import { handlePendingWecomContactBindMessage } from '../../channels/wecom.js';
+import { handlePendingDingtalkContactBindMessage, registerPendingDingtalkContactBind } from '../../channels/dingtalk.js';
+import { handlePendingFeishuContactBindMessage, registerPendingFeishuContactBind } from '../../channels/feishu.js';
+import { handlePendingQQBotContactBindMessage, registerPendingQQBotContactBind } from '../../channels/qqbot.js';
+import { handlePendingWecomContactBindMessage, registerPendingWecomContactBind } from '../../channels/wecom.js';
+import { handlePendingWechatContactBindMessage, registerPendingWechatContactBind } from '../../channels/wechat.js';
 import { authorizeAccess, buildAuthSubject } from '../auth/auth-gateway.js';
 import { MenuDiagnosticLimiter, MenuRequestDeduper, hasValidMenuId, menuFailure, menuPayloadFingerprint, menuSuccess, normalizeMenuError, parseMenuControl, validateMenuRequest, } from '../command/menu-protocol.js';
+import { evaluateEvolMenuVersionGate, evolMenuResponseTransportMetadata, isAunMenuTokenRequired } from '../command/evol-menu-version-gate.js';
+import { MenuTokenStore } from '../command/menu-token-store.js';
 import { SessionRenewService } from '../session/session-renew.js';
 import { createRootCausation, deriveCausation, normalizeCausation } from '../causation/context.js';
 import { recordCausationSpan } from '../causation/audit.js';
+import { renderActionAsText } from '../interaction-router.js';
+import { planApprovalRoute } from '../permission/approval-gateway.js';
+import { consumeAdmissionReplyBudget, clearAdmissionReplyBudgets, evaluateInboundAdmissionPreflight, evaluateOrdinaryInboundAdmission, } from './inbound-admission.js';
 const CONTACT_REJECTION_NOTICE = '[rejection] Not accepting messages from you.';
 const REJECTABLE_PEER_TYPES = new Set(['ai', 'bot', 'agent', 'service']);
 const REJECTION_MAX = 3;
 const REJECTION_WINDOW_MS = 60 * 60 * 1000;
 const rejectionState = new Map();
+const SELF_SERVICE_CONTACT_BIND_TYPES = ['feishu', 'dingtalk', 'wecom', 'qqbot', 'wechat'];
+const SELF_SERVICE_CONTACT_BIND_DISPLAY = {
+    feishu: '飞书',
+    dingtalk: '钉钉',
+    wecom: '企微',
+    qqbot: 'QQ',
+    wechat: '微信',
+};
 export function shouldBlockInboundContact(input) {
-    if (String(input.channelType || '').trim().toLowerCase() !== 'aun' || !input.selfAid) {
+    if (!input.selfAid) {
         return { blocked: false, status: 'unsupported-channel' };
     }
     if (input.chatType !== 'private')
         return { blocked: false, status: 'unsupported-chat' };
-    const primaryId = String(input.actorId || '').trim();
-    if (!isValidAid(primaryId))
+    const channelType = String(input.channelType || '').trim().toLowerCase();
+    if (channelType !== 'aun' && !input.channelKey) {
+        return { blocked: false, status: 'unsupported-channel' };
+    }
+    const actorId = String(input.actorId || '').trim();
+    const resolution = resolvePrincipal(input.selfAid, channelType, actorId, input.channelKey);
+    const primaryId = resolution.principalId;
+    if (!primaryId)
         return { blocked: false, status: 'invalid-aid' };
-    if (input.chatType === 'private' && resolveContactView(input.selfAid, primaryId).isOwner) {
+    if (resolveContactView(input.selfAid, primaryId).isOwner) {
         return { blocked: false, status: 'owner-exempt', primaryId };
     }
     return {
-        blocked: isBlockedContact(input.selfAid, primaryId),
+        blocked: resolveContactView(input.selfAid, primaryId).blocked,
         status: 'resolved',
         primaryId,
     };
@@ -56,6 +79,7 @@ export function shouldSendContactRejection(peerType, selfAid, primaryId, now = D
 }
 export function clearContactRejectionRateLimits() {
     rejectionState.clear();
+    clearAdmissionReplyBudgets();
 }
 /**
  * MessageBridge — Channel 与 Core 之间的消息桥梁
@@ -78,8 +102,12 @@ export class MessageBridge {
     bootstrapService;
     menuDeduper = new MenuRequestDeduper();
     menuDiagnostics = new MenuDiagnosticLimiter();
+    menuTokenStore = new MenuTokenStore();
     handoffRuntime;
     sessionRenewService;
+    aidStatsCollector;
+    contactBindRuntimeChecker;
+    interactionRouter;
     constructor(defaultProjectPath, sessionManager, processor, messageQueue, cmdHandler, eventBus, defaultDebounce, processOwnersProvider) {
         this.defaultProjectPath = defaultProjectPath;
         this.sessionManager = sessionManager;
@@ -89,7 +117,7 @@ export class MessageBridge {
         this.eventBus = eventBus;
         this.processOwnersProvider = processOwnersProvider;
         this.defaultDebounce = defaultDebounce ?? 0;
-        this.sessionRenewService = new SessionRenewService(sessionManager, processor);
+        this.sessionRenewService = new SessionRenewService(sessionManager, processor, { eventBus });
     }
     /** Inject EvolAgentRegistry so owner lookups/writes route to agent.json for agent-owned channels. */
     setAgentRegistry(registry) {
@@ -98,9 +126,388 @@ export class MessageBridge {
     setBootstrapService(service) {
         this.bootstrapService = service;
     }
+    /** 非 AUN 渠道的 per-AID 消息统计由本桥梁记账（AUN 在 channel 层自行记账） */
+    setAidStatsCollector(collector) {
+        this.aidStatsCollector = collector;
+    }
     setHandoffRuntime(runtime) {
         this.handoffRuntime = runtime;
     }
+    setContactBindRuntimeChecker(checker) {
+        this.contactBindRuntimeChecker = checker;
+    }
+    setInteractionRouter(router) {
+        this.interactionRouter = router;
+    }
+    /**
+     * AUN supplies an authenticated sender AID, while the IM-side code proves
+     * possession of the external account. This command only creates that
+     * identity mapping; it never changes a role assignment.
+     */
+    handleAunSelfServiceContactBind(input) {
+        const match = /^\s*\/bind(?:\s+(.+?))?\s*$/i.exec(input.content);
+        if (!match)
+            return { handled: false };
+        if (input.chatType !== 'private') {
+            return {
+                handled: true,
+                status: 'private-only',
+                reply: '联系人绑定只能在 AUN 私聊中发起。用法：/bind <渠道> [实例名]。',
+            };
+        }
+        const selfAid = String(input.selfAid || '').trim();
+        const actorId = String(input.actorId || '').trim();
+        if (!isValidAid(selfAid) || !isValidAid(actorId)) {
+            return {
+                handled: true,
+                status: 'invalid-aid',
+                reply: '无法验证当前 AUN 身份，未创建联系人绑定码。请通过已认证的 AUN 私聊重新发送请求。',
+            };
+        }
+        const args = String(match[1] || '').trim().split(/\s+/).filter(Boolean);
+        if (args.length < 1 || args.length > 2) {
+            return { handled: true, status: 'format', reply: this.aunSelfServiceBindUsage() };
+        }
+        const channelType = args[0].toLowerCase();
+        if (!SELF_SERVICE_CONTACT_BIND_TYPES.includes(channelType)) {
+            return { handled: true, status: 'unsupported-channel', reply: this.aunSelfServiceBindUsage() };
+        }
+        const agent = input.owningAgent ?? this.agentRegistry?.get(selfAid);
+        if (!agent || agent.aid !== selfAid) {
+            return {
+                handled: true,
+                status: 'agent-unavailable',
+                reply: '目标 Agent 当前不可用，未创建联系人绑定码。',
+            };
+        }
+        const instances = (agent.config.channels ?? []).filter((instance) => (String(instance?.type || '').trim().toLowerCase() === channelType
+            && instance.enabled !== false
+            && typeof instance.name === 'string'
+            && instance.name.trim().length > 0));
+        const requestedInstance = args[1];
+        let instance;
+        if (requestedInstance) {
+            instance = instances.find((candidate) => candidate.name === requestedInstance);
+            if (!instance) {
+                return {
+                    handled: true,
+                    status: 'unknown-instance',
+                    reply: `未找到已启用的 ${SELF_SERVICE_CONTACT_BIND_DISPLAY[channelType]} 实例 “${requestedInstance}”。${this.aunSelfServiceBindInstances(channelType, instances)}`,
+                };
+            }
+        }
+        else if (instances.length === 1) {
+            instance = instances[0];
+        }
+        else if (instances.length === 0) {
+            return {
+                handled: true,
+                status: 'not-configured',
+                reply: `目标 Agent 未启用 ${SELF_SERVICE_CONTACT_BIND_DISPLAY[channelType]} 机器人，无法创建联系人绑定码。`,
+            };
+        }
+        else {
+            return {
+                handled: true,
+                status: 'instance-required',
+                reply: `该 Agent 有多个 ${SELF_SERVICE_CONTACT_BIND_DISPLAY[channelType]} 实例。${this.aunSelfServiceBindInstances(channelType, instances)}`,
+            };
+        }
+        const channelName = formatChannelKey({ type: channelType, selfAID: selfAid, name: instance.name });
+        const runtimeAvailable = this.contactBindRuntimeChecker
+            ? this.contactBindRuntimeChecker(channelName)
+            : !!this.processor.getChannelInfo?.(channelName);
+        if (!runtimeAvailable) {
+            return {
+                handled: true,
+                status: 'runtime-unavailable',
+                reply: `${SELF_SERVICE_CONTACT_BIND_DISPLAY[channelType]}实例当前未连接，未创建联系人绑定码。请等待机器人上线后重试。`,
+            };
+        }
+        const result = this.registerSelfServiceContactBind({
+            channelType,
+            selfAid,
+            channelName,
+            primaryId: actorId,
+        });
+        if (!result.ok) {
+            logger.warn(`[MessageBridge] Failed to register AUN self-service contact bind: self=${selfAid} actor=${actorId} channel=${channelName} error=${result.error}`);
+            return {
+                handled: true,
+                status: 'register-failed',
+                reply: `未能创建${SELF_SERVICE_CONTACT_BIND_DISPLAY[channelType]}身份绑定码：${result.error}。请稍后重试。`,
+            };
+        }
+        return {
+            handled: true,
+            status: result.replaced ? 'replaced' : 'issued',
+            reply: `请在 ${SELF_SERVICE_CONTACT_BIND_DISPLAY[channelType]} 机器人私聊中发送 /bind ${result.code} 完成联系人绑定。绑定 10 分钟内有效，不会修改 Owner、Admin 或关系角色配置。`,
+        };
+    }
+    registerSelfServiceContactBind(input) {
+        switch (input.channelType) {
+            case 'feishu': return registerPendingFeishuContactBind(input);
+            case 'dingtalk': return registerPendingDingtalkContactBind(input);
+            case 'wecom': return registerPendingWecomContactBind(input);
+            case 'qqbot': return registerPendingQQBotContactBind(input);
+            case 'wechat': return registerPendingWechatContactBind(input);
+        }
+    }
+    aunSelfServiceBindUsage() {
+        return `用法：/bind <渠道> [实例名]。支持渠道：${SELF_SERVICE_CONTACT_BIND_TYPES.join('、')}。`;
+    }
+    aunSelfServiceBindInstances(channelType, instances) {
+        const names = instances.map(instance => String(instance.name || '').trim()).filter(Boolean);
+        return names.length > 0
+            ? `可用实例：${names.join('、')}。请发送 /bind ${channelType} <实例名>。`
+            : '';
+    }
+    async handleReservedContactControl(input) {
+        const { context, msg, content, owningAgent, sendReply } = input;
+        const bindContext = {
+            selfAid: context.selfAid,
+            channelName: context.channelKey,
+            channelType: context.channelType,
+            chatType: context.chatType,
+            actorId: context.actorId,
+            content,
+        };
+        const contactBind = context.channelType === 'dingtalk'
+            ? handlePendingDingtalkContactBindMessage(bindContext)
+            : context.channelType === 'feishu'
+                ? handlePendingFeishuContactBindMessage(bindContext)
+                : context.channelType === 'wecom'
+                    ? handlePendingWecomContactBindMessage(bindContext)
+                    : context.channelType === 'qqbot'
+                        ? handlePendingQQBotContactBindMessage(bindContext)
+                        : context.channelType === 'wechat'
+                            ? handlePendingWechatContactBindMessage(bindContext)
+                            : { handled: false };
+        if (contactBind.handled) {
+            logger.info(`[MessageBridge] ${context.channelType} contact bind handled before admission: channel=${context.channelKey} actor=${context.actorId || '<none>'} status=${contactBind.status}`);
+            if (contactBind.reply) {
+                await this.sendAdmissionControlReply(context, msg, sendReply, contactBind.reply);
+            }
+            return true;
+        }
+        if (context.channelType === 'aun') {
+            const aunSelfServiceBind = this.handleAunSelfServiceContactBind({
+                selfAid: context.selfAid,
+                actorId: context.actorId,
+                chatType: context.chatType,
+                content,
+                owningAgent,
+            });
+            if (aunSelfServiceBind.handled) {
+                logger.info(`[MessageBridge] AUN self-service contact bind handled before admission: channel=${context.channelKey} actor=${context.actorId || '<none>'} status=${aunSelfServiceBind.status}`);
+                if (aunSelfServiceBind.reply) {
+                    await this.sendAdmissionControlReply(context, msg, sendReply, aunSelfServiceBind.reply);
+                }
+                return true;
+            }
+        }
+        const requestMatch = /^\s*\/request(?:\s+([\s\S]*?))?\s*$/i.exec(content);
+        if (!requestMatch)
+            return false;
+        if (context.channelType !== 'aun') {
+            await this.sendAdmissionControlReply(context, msg, sendReply, '联系人申请仅支持 AUN 私聊。');
+            return true;
+        }
+        if (context.chatType !== 'private') {
+            await this.sendAdmissionControlReply(context, msg, sendReply, '联系人申请仅支持 AUN 私聊。');
+            return true;
+        }
+        if (!context.primaryId) {
+            await this.sendAdmissionControlReply(context, msg, sendReply, '无法验证当前 AUN 身份，未提交联系人申请。');
+            return true;
+        }
+        let result;
+        try {
+            result = await submitContactRequest({
+                selfAid: context.selfAid,
+                applicantAid: context.primaryId,
+                note: requestMatch[1],
+                sourceChannelKey: context.channelKey,
+            });
+        }
+        catch (error) {
+            logger.warn(`[MessageBridge] Contact request submission failed: self=${context.selfAid} applicant=${context.primaryId} error=${error instanceof Error ? error.message : String(error)}`);
+            await this.sendAdmissionControlReply(context, msg, sendReply, '当前无法受理联系人申请，请稍后再试。');
+            return true;
+        }
+        if ((result.code === 'submitted' || result.code === 'resubmitted') && result.requestId) {
+            void this.deliverContactReviewCard(context.selfAid, context.primaryId, result, owningAgent)
+                .catch(error => logger.warn(`[MessageBridge] Contact review delivery failed: self=${context.selfAid} applicant=${context.primaryId} error=${error instanceof Error ? error.message : String(error)}`));
+        }
+        await this.sendAdmissionControlReply(context, msg, sendReply, this.contactRequestReply(result));
+        return true;
+    }
+    async sendAdmissionControlReply(context, msg, sendReply, text) {
+        if (!text || !consumeAdmissionReplyBudget(context))
+            return false;
+        await sendReply(msg.channelId, text, msg.replyContext);
+        return true;
+    }
+    admissionDeniedNotice(context, channelType) {
+        if (context.contactStatus === 'pending') {
+            return '联系人申请审核中；可再次发送 /request 更新说明。';
+        }
+        if (context.contactSource === 'contact' && context.contactStatus === 'active') {
+            return '当前不接受任何消息。';
+        }
+        if (channelType === 'aun') {
+            return '当前不接受陌生人消息。可发送 /request <申请说明> 申请成为联系人。';
+        }
+        return '当前不接受陌生人消息。联系人申请仅支持 AUN 私聊。';
+    }
+    contactRequestReply(result) {
+        switch (result.code) {
+            case 'submitted': return '联系人申请已提交，等待管理员审核。';
+            case 'resubmitted': return '联系人申请已更新，等待管理员审核。';
+            case 'already-contact': return '你已经是联系人。';
+            case 'owner': return '你已经是 Owner。';
+            case 'blocked': return CONTACT_REJECTION_NOTICE;
+            case 'rate-limited': return '联系人申请过于频繁，请稍后再试。';
+            case 'capacity': return '当前申请较多，请稍后再试。';
+            case 'no-owner': return '当前无法受理联系人申请。';
+            case 'invalid-applicant': return '无法验证当前 AUN 身份，未提交联系人申请。';
+            case 'invalid-note': return '申请说明不能超过 500 个字符。';
+        }
+    }
+    async deliverContactReviewCard(selfAid, applicantAid, submission, owningAgent) {
+        if (!this.interactionRouter || !submission.requestId || !submission.expiresAt || !submission.submittedAt) {
+            return false;
+        }
+        const ownerAdapterKey = formatChannelKey({ type: 'aun', selfAID: selfAid, name: 'main' });
+        const ownerAdapter = this.processor.getChannelInfo?.(ownerAdapterKey)?.adapter;
+        const resolveApproverCandidates = () => ({
+            owners: listStaticAgentOwners(selfAid, { fresh: true }),
+            admins: listStaticAgentAdmins(selfAid, { fresh: true }),
+        });
+        const { owners, admins } = resolveApproverCandidates();
+        const route = planApprovalRoute({
+            id: submission.requestId,
+            sessionId: `contact-request:${selfAid}:${submission.requestId}`,
+            toolName: 'contact.request.review',
+            toolInput: { applicantAid, requestId: submission.requestId },
+            summary: `Review contact request from ${applicantAid}`,
+            grantable: true,
+            approverPolicy: 'agent_manager',
+            createdAt: Date.parse(submission.submittedAt),
+        }, {
+            userId: applicantAid,
+            chatType: 'private',
+            selfAid,
+            approvalRouting: {
+                approverPolicy: 'agent_manager',
+                owners,
+                admins,
+                resolveApproverCandidates,
+                ownerAdapter,
+                forceHandoff: true,
+                selfAid,
+                originSessionId: `contact-request:${selfAid}:${submission.requestId}`,
+                originChannel: 'aun',
+                originChannelId: applicantAid,
+                originPeerId: applicantAid,
+                originPrincipalId: applicantAid,
+            },
+        });
+        if (route.kind !== 'handoff') {
+            logger.warn(`[MessageBridge] Contact review route unavailable: self=${selfAid} request=${submission.requestId} reason=${route.kind === 'unavailable' ? route.reason : 'local-route-not-allowed'}`);
+            return false;
+        }
+        let note = '申请说明不可用';
+        try {
+            note = findContactRequestNote(selfAid, submission.requestId) || '（未填写）';
+        }
+        catch { }
+        const expiresAtMs = Date.parse(submission.expiresAt);
+        const sessionId = `contact-request:${selfAid}:${submission.requestId}`;
+        const interaction = {
+            type: 'interaction',
+            id: submission.requestId,
+            channelId: route.approverOperatorId,
+            sessionId,
+            initiatorId: route.approverOperatorId,
+            expiresAt: expiresAtMs,
+            kind: {
+                kind: 'action',
+                title: '联系人申请审核',
+                bodyFormat: 'plain',
+                body: `申请人：${applicantAid}\n申请说明：${note}\n提交时间：${submission.submittedAt}\n截止时间：${submission.expiresAt}\n\n此卡片只处理当前这一次联系人申请。申请人重新提交、已被他人处理或审批超时，均不会修改当前联系人状态。卡片因重启或投递失效时，可在联系人列表处理仍未到期的 pending；已过期申请需由申请人重新发送 /request。`,
+                buttons: [
+                    { key: 'approve', label: '通过', style: 'primary' },
+                    { key: 'reject', label: '拒绝', style: 'default' },
+                    { key: 'block', label: '拉黑', style: 'danger', confirm: { title: '拉黑申请人', body: `确定拉黑 ${applicantAid}？` } },
+                ],
+            },
+        };
+        this.interactionRouter.register(submission.requestId, sessionId, async (action, _values, operatorId) => {
+            if (action !== 'approve' && action !== 'reject' && action !== 'block')
+                return false;
+            const reviewed = await reviewContactRequest({
+                selfAid,
+                primaryId: applicantAid,
+                requestId: submission.requestId,
+                expectedContactRevision: submission.contactRevision,
+                approverId: route.approverOperatorId,
+                actorId: String(operatorId || ''),
+                decision: action,
+            });
+            try {
+                await this.sendContactReviewOutcome(route.adapter, route.approverOperatorId, applicantAid, reviewed.code, owningAgent?.name);
+            }
+            catch (error) {
+                logger.warn(`[MessageBridge] Contact review outcome notification failed: request=${submission.requestId} error=${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (reviewed.code === 'approved' || reviewed.code === 'rejected' || reviewed.code === 'blocked') {
+                try {
+                    await this.notifyContactApplicant(route.adapter, applicantAid, reviewed.code, owningAgent?.name);
+                }
+                catch (error) {
+                    logger.warn(`[MessageBridge] Contact applicant notification failed: request=${submission.requestId} error=${error instanceof Error ? error.message : String(error)}`);
+                }
+                return true;
+            }
+            return false;
+        }, {
+            timeoutMs: Math.max(1, expiresAtMs - Date.now()),
+            initiatorId: route.approverOperatorId,
+            initiatorChannelKey: route.approverChannelKey,
+            onTimeout: () => { void expirePendingContactRequests(selfAid); },
+            onCancel: reason => route.adapter.invalidateInteraction?.(submission.requestId, reason),
+        });
+        const envelope = buildEnvelope({
+            taskId: `contact-request-${submission.requestId}`,
+            sessionId,
+            channel: route.adapter.channelName,
+            channelId: route.approverOperatorId,
+            agentName: owningAgent?.name ?? selfAid,
+            chatmode: 'interactive',
+            replyContext: { metadata: { source: 'handoff', chatmode: 'interactive' } },
+        });
+        const sent = await sendInteractionPayload(route.adapter, envelope, interaction, renderActionAsText(interaction), envelope.replyContext);
+        if (!sent)
+            await this.interactionRouter.cancel(submission.requestId, 'delivery_failed');
+        return !!sent;
+    }
+    async sendContactReviewOutcome(adapter, ownerAid, applicantAid, code, agentName) {
+        const text = code === 'approved' ? `已通过 ${applicantAid} 的联系人申请。`
+            : code === 'rejected' ? `已拒绝 ${applicantAid} 的联系人申请。`
+                : code === 'blocked' ? `已拉黑 ${applicantAid}。`
+                    : code === 'request-expired' ? '审核已过期。'
+                        : code === 'request-stale' ? '申请已更新或已被处理。'
+                            : code === 'revision-conflict' ? '联系人列表已变化，请从联系人列表重新审核。'
+                                : '当前无审核权限。';
+        await adapter.send(buildEnvelope({ channel: adapter.channelName, channelId: ownerAid, agentName: agentName ?? '<unknown>' }), { kind: 'system.notice', text, subtype: 'contact-review' });
+    }
+    async notifyContactApplicant(adapter, applicantAid, code, agentName) {
+        const text = code === 'approved' ? '你的联系人申请已通过。'
+            : code === 'rejected' ? '你的联系人申请未通过。'
+                : '你的联系人申请未通过。';
+        await adapter.send(buildEnvelope({ channel: adapter.channelName, channelId: applicantAid, agentName: agentName ?? '<unknown>' }), { kind: 'system.notice', text, subtype: 'contact-request-result' });
+    }
     getDebouncer(channelName, channelType) {
         let d = this.debouncers.get(channelName);
         if (!d) {
@@ -163,23 +570,58 @@ export class MessageBridge {
                 const conversationId = chatType === 'group' ? (msg.groupId || msg.channelId) : msg.peerId;
                 const selfAid = msg.selfAID || owningAgent?.aid || parsedChannelKey?.selfAID;
                 const resolvedChannelType = msg.channelType || parsedChannelKey?.type || effectiveChannelType;
-                const blockDecision = shouldBlockInboundContact({
+                const trustedHandoffEcho = msg.source === 'handoff'
+                    && resolvedChannelType === 'aun'
+                    && !!selfAid
+                    && actorId === selfAid;
+                const admissionPreflight = evaluateInboundAdmissionPreflight({
                     selfAid,
+                    channelKey,
                     channelType: resolvedChannelType,
                     chatType,
                     actorId,
-                    conversationId,
+                    trustedHandoffEcho,
                 });
-                if (blockDecision.blocked && selfAid && blockDecision.primaryId) {
-                    let peerType = msg.peerType;
-                    if (chatType === 'private' && !peerType) {
-                        peerType = PeerIdentityCache.get('aun', blockDecision.primaryId, agentDir(selfAid))?.type;
+                if (!admissionPreflight.allow) {
+                    const requestCommand = /^\s*\/request(?:\s|$)/i.test(content);
+                    if (admissionPreflight.reason === 'blocked' && admissionPreflight.context.primaryId) {
+                        const primaryId = admissionPreflight.context.primaryId;
+                        let peerType = msg.peerType;
+                        if (chatType === 'private' && !peerType) {
+                            peerType = PeerIdentityCache.get('aun', primaryId, agentDir(selfAid))?.type;
+                        }
+                        if (chatType === 'private'
+                            && REJECTABLE_PEER_TYPES.has(String(peerType || '').trim().toLowerCase())) {
+                            await this.sendAdmissionControlReply(admissionPreflight.context, msg, sendReply, CONTACT_REJECTION_NOTICE);
+                        }
+                        logger.info(`[MessageBridge] Blocked canonical inbound before business routing: self=${selfAid} peer=${primaryId} type=${peerType ?? 'unknown'} channel=${channelKey}`);
+                    }
+                    else if (admissionPreflight.reason === 'restricted_mode_without_owner' && requestCommand) {
+                        await this.sendAdmissionControlReply(admissionPreflight.context, msg, sendReply, '当前无法受理联系人申请。');
                     }
-                    if (chatType === 'private'
-                        && shouldSendContactRejection(peerType, selfAid, blockDecision.primaryId)) {
-                        await sendReply(msg.channelId, CONTACT_REJECTION_NOTICE, msg.replyContext);
+                    else {
+                        logger.warn(`[MessageBridge] Admission preflight denied: self=${selfAid ?? '<none>'} actor=${actorId ?? '<none>'} channel=${channelKey} reason=${admissionPreflight.reason}`);
                     }
-                    logger.info(`[MessageBridge] Blocked AUN inbound before business routing: self=${selfAid} peer=${blockDecision.primaryId} type=${peerType ?? 'unknown'} chatType=${chatType}`);
+                    return;
+                }
+                if (!trustedHandoffEcho && await this.handleReservedContactControl({
+                    context: admissionPreflight.context,
+                    msg,
+                    content,
+                    owningAgent,
+                    sendReply,
+                })) {
+                    return;
+                }
+                const admissionDecision = evaluateOrdinaryInboundAdmission(admissionPreflight.context);
+                if (!admissionDecision.allow) {
+                    if (chatType === 'private') {
+                        const notice = this.admissionDeniedNotice(admissionDecision.context, resolvedChannelType);
+                        if (notice) {
+                            await this.sendAdmissionControlReply(admissionDecision.context, msg, sendReply, notice);
+                        }
+                    }
+                    logger.info(`[MessageBridge] Inbound admission denied before business routing: self=${selfAid} actor=${actorId ?? '<none>'} channel=${channelKey} reason=${admissionDecision.reason}`);
                     return;
                 }
                 const menuControl = resolvedChannelType === 'aun'
@@ -191,39 +633,46 @@ export class MessageBridge {
                         this.logMenuDiagnostic('missing-id', channelName, msg, menuControl);
                         return;
                     }
-                    const validationError = validateMenuRequest(menuControl.request);
-                    if (validationError) {
+                    const versionError = evaluateEvolMenuVersionGate({
+                        encrypted: msg.encrypted,
+                        protectedHeaders: msg.protectedHeaders,
+                    });
+                    if (versionError) {
                         const header = { id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) };
-                        await this.sendMenuResponse(adapter, channelName, msg, menuFailure(header, validationError));
+                        await this.sendMenuResponse(adapter, channelName, msg, menuFailure(header, versionError));
                         return;
                     }
-                }
-                if (!menuControl.isMenu) {
-                    const bindContext = {
-                        selfAid,
-                        channelName: channelKey,
-                        channelType: resolvedChannelType,
-                        chatType,
-                        actorId,
-                        content,
-                    };
-                    const contactBind = resolvedChannelType === 'dingtalk'
-                        ? handlePendingDingtalkContactBindMessage(bindContext)
-                        : resolvedChannelType === 'wecom'
-                            ? handlePendingWecomContactBindMessage(bindContext)
-                            : { handled: false };
-                    if (contactBind.handled) {
-                        logger.info(`[MessageBridge] ${resolvedChannelType} contact bind handled: channel=${channelKey} actor=${actorId ?? '<none>'} status=${contactBind.status}`);
-                        if (contactBind.reply) {
-                            await sendReply(msg.channelId, contactBind.reply, msg.replyContext);
+                    const header = { id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) };
+                    const isTokenRequest = menuControl.type === 'menu.token.request';
+                    const menuTokenRequired = isAunMenuTokenRequired();
+                    if ((menuTokenRequired || isTokenRequest) && !msg.encrypted) {
+                        await this.sendMenuResponse(adapter, channelName, msg, menuFailure(header, {
+                            code: 'MENU_TOKEN_ENCRYPTION_REQUIRED',
+                            message: 'Menu 请求必须使用 E2EE',
+                        }), true);
+                        return;
+                    }
+                    if (!isTokenRequest) {
+                        const tokenOwnerAid = this.menuTokenOwnerAid(channelName, msg);
+                        const tokenSupplied = Object.prototype.hasOwnProperty.call(menuControl.request, 'menu_token');
+                        const tokenValid = (menuTokenRequired || tokenSupplied)
+                            && !!tokenOwnerAid
+                            && this.menuTokenStore.use(tokenOwnerAid, msg.peerId, menuControl.request.menu_token);
+                        if (menuTokenRequired && !tokenValid) {
+                            this.logMenuDiagnostic('token-required', channelName, msg, menuControl, 'MENU_TOKEN_REQUIRED');
+                            await this.sendMenuResponse(adapter, channelName, msg, menuFailure(header, {
+                                code: 'MENU_TOKEN_REQUIRED',
+                                message: 'Menu token 无效或已过期，请发送 menu.token.request 重新申请',
+                            }));
+                            return;
                         }
+                    }
+                    const validationError = validateMenuRequest(menuControl.request);
+                    if (validationError) {
+                        await this.sendMenuResponse(adapter, channelName, msg, menuFailure(header, validationError));
                         return;
                     }
                 }
-                const trustedHandoffEcho = msg.source === 'handoff'
-                    && resolvedChannelType === 'aun'
-                    && !!selfAid
-                    && actorId === selfAid;
                 const roleDetail = trustedHandoffEcho
                     ? {
                         effectiveRole: 'owner',
@@ -284,6 +733,18 @@ export class MessageBridge {
                     logger.debug(`[MessageBridge] Transient protocol message ignored: channel=${channelName} type=${msg.payloadType || msg.msgType || '<unknown>'}`);
                     return;
                 }
+                // 0.5 Per-AID 消息统计（预览行/tooltip 数据源）。
+                // AUN 在 channel 层自行记账（早于本桥梁，且含协议细节），这里只补非 AUN 渠道，避免重复计数。
+                if (resolvedChannelType !== 'aun' && selfAid) {
+                    this.aidStatsCollector?.recordInbound(selfAid, conversationId || msg.channelId, Buffer.byteLength(content, 'utf-8'), content, false, undefined, undefined, 'send', {
+                        channelType: resolvedChannelType,
+                        // 联系人簿的 displayName 是本端主动命名，优先于渠道昵称；都没有才退回原生 ID
+                        peerLabel: resolvePeerDisplayLabel(selfAid, resolvedChannelType, actorId ?? '', channelKey)
+                            || msg.peerName || actorId || msg.channelId,
+                        // 飞书私聊的 channelId 是 oc_*、peerId 是 ou_*；缓存二者关联供所有出站类型复用。
+                        ...(chatType === 'private' ? { routeId: msg.channelId } : {}),
+                    });
+                }
                 // 1. owner 绑定（按实例名绑定）
                 if (adapter && actorId && roleDetail.effectiveRole === 'owner') {
                     await this.bootstrapService?.tryStartBootstrap({
@@ -382,6 +843,12 @@ export class MessageBridge {
                 const replyToMessageId = typeof msg.replyContext?.metadata?.refMessageId === 'string'
                     ? msg.replyContext.metadata.refMessageId
                     : msg.replyContext?.replyToMessageId ?? null;
+                const restoredCausation = (msg.channelType || effectiveChannelType) === 'aun'
+                    ? normalizeCausation(msg.causation)
+                    : undefined;
+                const inboundCausation = restoredCausation
+                    ? deriveCausation(restoredCausation)
+                    : createRootCausation();
                 const renewResult = await this.sessionRenewService.resolve({
                     session,
                     channelName,
@@ -395,6 +862,7 @@ export class MessageBridge {
                     content,
                     replyToMessageId,
                     isNewSession: !hadMainSession,
+                    causation: inboundCausation,
                 });
                 session = renewResult.session;
                 // 4. 群聊发送者标注由消息渲染层（message-renderer）逐条承担，不再在此硬编码前缀，
@@ -422,19 +890,15 @@ export class MessageBridge {
                     topicName: this.extractTopicName(msg),
                     replyContext: msg.replyContext,
                     source: msg.source,
+                    boundSessionId: session.id,
+                    resolvedIdentity: identity,
                     dispatchMode: msg.dispatchMode,
-                    causation: (() => {
-                        const restored = (msg.channelType || effectiveChannelType) === 'aun'
-                            ? normalizeCausation(msg.causation)
-                            : undefined;
-                        const inbound = restored ? deriveCausation(restored) : createRootCausation();
-                        recordCausationSpan(inbound, 'message.inbound', {
-                            status: 'completed',
-                            refs: { messageId: msg.messageId, sessionId: session.id },
-                        });
-                        return inbound;
-                    })(),
+                    causation: inboundCausation,
                 };
+                recordCausationSpan(inboundCausation, 'message.inbound', {
+                    status: 'completed',
+                    refs: { messageId: msg.messageId, sessionId: session.id },
+                });
                 const inboundEntry = (() => {
                     const chatDir = this.sessionManager.getChatDir(session);
                     const inboundEncrypt = msg.replyContext?.metadata?.encrypted != null ? !!(msg.replyContext.metadata.encrypted) : undefined;
@@ -564,6 +1028,7 @@ export class MessageBridge {
         effort: '/effort',
         chatmode: '/chatmode',
         mentionmode: '/mentionmode',
+        group: '/group',
         permission: '/perm',
         activity: '/activity',
         observable: '/observable',
@@ -574,6 +1039,7 @@ export class MessageBridge {
         file: '/file',
         capability: '/capability',
         role: '/role',
+        connect: '/connect',
     };
     extractTopicName(msg) {
         const raw = msg.topicName
@@ -612,18 +1078,40 @@ export class MessageBridge {
         if (!hasValidMenuId(parsed))
             return;
         const header = { id: parsed.id, ...(parsed.name?.trim() ? { name: parsed.name } : {}) };
-        const access = authorizeAccess(authSubject);
-        if (!access.allow) {
-            this.logMenuDiagnostic('access-denied', channel, msg, parsed, access.code);
-            await this.sendMenuResponse(adapter, channel, msg, menuFailure(header, {
-                code: 'ROLE_ACCESS_DENIED',
-                message: access.reason,
-            }));
-            return;
+        const isTokenRequest = parsed.type === 'menu.token.request';
+        if (isTokenRequest) {
+            if (msg.chatType !== 'private') {
+                await this.sendMenuResponse(adapter, channel, msg, menuFailure(header, {
+                    code: 'MENU_TOKEN_REJECTED',
+                    message: '授权申请未通过',
+                }));
+                return;
+            }
+            if (!this.menuTokenOwnerAid(channel, msg) || !msg.peerId) {
+                await this.sendMenuResponse(adapter, channel, msg, menuFailure(header, {
+                    code: 'MENU_TOKEN_REJECTED',
+                    message: '授权申请未通过',
+                }));
+                return;
+            }
+        }
+        if (!isTokenRequest) {
+            const access = authorizeAccess(authSubject);
+            if (!access.allow) {
+                this.logMenuDiagnostic('access-denied', channel, msg, parsed, access.code);
+                await this.sendMenuResponse(adapter, channel, msg, menuFailure(header, {
+                    code: 'ROLE_ACCESS_DENIED',
+                    message: access.reason,
+                }));
+                return;
+            }
         }
         const scope = msg.chatType === 'group' ? (msg.groupId || msg.channelId) : msg.peerId;
         const dedupKey = [msg.selfAID || channel, channelType, msg.chatType || 'private', scope, msg.peerId, msg.threadId || '', parsed.id].join('\u001f');
-        const deduped = await this.menuDeduper.execute(dedupKey, menuPayloadFingerprint(parsed.raw), () => this.dispatchMenuRequest(parsed.request, header, channel, msg, authSubject));
+        let afterResponse;
+        const deduped = await this.menuDeduper.execute(dedupKey, menuPayloadFingerprint(parsed.raw), () => isTokenRequest
+            ? this.issueMenuTokenResponse(header, channel, msg)
+            : this.dispatchMenuRequest(parsed.request, header, channel, msg, authSubject, effect => { afterResponse = effect; }));
         if ('conflict' in deduped) {
             this.logMenuDiagnostic('request-conflict', channel, msg, parsed, 'CONFLICT');
             await this.sendMenuResponse(adapter, channel, msg, menuFailure(header, {
@@ -634,9 +1122,18 @@ export class MessageBridge {
         }
         if (deduped.replayed)
             this.logMenuDiagnostic('request-replay', channel, msg, parsed);
-        await this.sendMenuResponse(adapter, channel, msg, deduped.value);
+        await this.sendMenuResponse(adapter, channel, msg, deduped.value, isTokenRequest);
+        const deferredEffect = afterResponse;
+        if (!deduped.replayed && deferredEffect) {
+            try {
+                await deferredEffect();
+            }
+            catch (error) {
+                logger.warn(`[MenuControl] deferred effect failed: request=${parsed.id} error=${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
     }
-    async dispatchMenuRequest(request, header, channel, msg, authSubject) {
+    async dispatchMenuRequest(request, header, channel, msg, authSubject, registerAfterResponse) {
         try {
             const identity = authSubject.identity;
             const name = header.name ?? '';
@@ -644,7 +1141,7 @@ export class MessageBridge {
             const args = request.args;
             switch (request.type) {
                 case 'menu.list':
-                    return menuSuccess(header, this.cmdHandler.getMenuItems(identity.role, msg.chatType || 'private', msg.isControlChannel ? 'control' : 'agent'));
+                    return menuSuccess(header, this.cmdHandler.getMenuItems(identity.role, msg.chatType || 'private', msg.isControlChannel ? 'control' : 'agent', authSubject));
                 case 'menu.query': {
                     const result = await this.cmdHandler.execMenuQuery(this.resolveCmd(name, cmd), channel, msg.channelId, msg.peerId, args, msg.chatType, msg.isControlChannel ?? false, identity, authSubject);
                     if ('error' in result)
@@ -676,7 +1173,9 @@ export class MessageBridge {
                         }
                         actionArgs = { ...(args ?? {}), targetThreadId: msg.threadId };
                     }
-                    const result = await this.cmdHandler.execMenuAction(this.resolveCmd(name, cmd), request.action, actionArgs, channel, msg.channelId, msg.peerId, identity, msg.chatType, header.id, msg.isControlChannel ?? false, authSubject);
+                    const resolvedCmd = this.resolveCmd(name, cmd);
+                    const isFileFetch = resolvedCmd.trim().split(' ')[0] === '/file' && request.action === 'fetch';
+                    const result = await this.cmdHandler.execMenuAction(resolvedCmd, request.action, actionArgs, channel, msg.channelId, msg.peerId, identity, msg.chatType, header.id, msg.isControlChannel ?? false, authSubject, 'menu', msg.replyContext, isFileFetch ? registerAfterResponse : undefined);
                     if ('error' in result)
                         throw result;
                     return menuSuccess(header, result.data);
@@ -692,7 +1191,7 @@ export class MessageBridge {
             return menuFailure(header, normalizeMenuError(error));
         }
     }
-    async sendMenuResponse(adapter, channel, msg, response) {
+    async sendMenuResponse(adapter, channel, msg, response, forceEncryption = false) {
         if (!adapter?.send) {
             this.logMenuDiagnostic('transport-unavailable', channel, msg, {
                 isMenu: true,
@@ -705,15 +1204,47 @@ export class MessageBridge {
             return;
         }
         const agentName = this.agentRegistry?.resolveByChannel(channel)?.name ?? '<unknown>';
+        const replyContext = {
+            ...(msg.replyContext ?? {}),
+            metadata: {
+                ...(msg.replyContext?.metadata ?? {}),
+                ...evolMenuResponseTransportMetadata(forceEncryption ? true : msg.encrypted),
+            },
+        };
         const envelope = buildEnvelope({
             taskId: `menu-${randomBytes(4).toString('hex')}`,
             channel,
             channelId: msg.channelId,
             agentName,
-            replyContext: msg.replyContext,
+            replyContext,
         });
         await adapter.send(envelope, { kind: 'custom', channelType: channel, payload: response });
     }
+    menuTokenOwnerAid(channel, msg) {
+        return msg.selfAID || this.agentRegistry?.resolveByChannel(channel)?.aid;
+    }
+    async issueMenuTokenResponse(header, channel, msg) {
+        const tokenOwnerAid = this.menuTokenOwnerAid(channel, msg);
+        if (!tokenOwnerAid || !msg.peerId) {
+            return menuFailure(header, { code: 'MENU_TOKEN_REJECTED', message: '授权申请未通过' });
+        }
+        const headers = msg.protectedHeaders ?? {};
+        const issued = this.menuTokenStore.issue(tokenOwnerAid, msg.peerId, {
+            clientName: this.menuTokenHeaderValue(headers.client_name ?? headers.app_name),
+            clientVersion: this.menuTokenHeaderValue(headers.client_version ?? headers.app_version),
+            evolVersion: this.menuTokenHeaderValue(headers.evol_version),
+        });
+        if (!issued) {
+            return menuFailure(header, { code: 'MENU_TOKEN_REJECTED', message: '授权申请未通过' });
+        }
+        return menuSuccess(header, { menu_token: issued.menuToken, idle_timeout: issued.idleTimeout });
+    }
+    menuTokenHeaderValue(value) {
+        if (typeof value !== 'string')
+            return undefined;
+        const normalized = value.trim();
+        return normalized.length > 0 && normalized.length <= 256 ? normalized : undefined;
+    }
     logMenuInbound(channel, msg, parsed) {
         logger.channelIn({
             channel,
@@ -816,8 +1347,19 @@ export class MessageBridge {
             }
             // 出站走 adapter.send 统一入口
             const adapter = this.processor.getChannelInfo?.(channel)?.adapter;
+            let responseSessionId;
+            try {
+                const responseSession = threadId
+                    ? await this.sessionManager.getThreadSession(channel, channelId, threadId)
+                    : await this.sessionManager.getActiveSession(channel, channelId);
+                responseSessionId = responseSession?.id;
+            }
+            catch (error) {
+                logger.debug(`[MessageBridge] Unable to bind command response session: ${error instanceof Error ? error.message : String(error)}`);
+            }
             const envelope = buildEnvelope({
                 taskId: `cmd-${randomBytes(5).toString('hex')}`,
+                sessionId: responseSessionId,
                 channel,
                 channelId,
                 agentName: this.agentRegistry?.resolveByChannel(channel)?.name ?? '<unknown>',