@zhin.js/core 1.5.2 → 1.5.4

package/lib/plugin-runtime/im/contracts.js

@@ -40,6 +40,9 @@ export class Message {
     metadata;
     segments;
     message;
+    endpointId;
+    mentioned;
+    replyTo;
     constructor(conversation, content, generation, reply, sender, metadata = Object.freeze({}), 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
@@ -47,7 +50,7 @@ export class Message {
      */
     segments, 
     /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
-    message) {
+    message, endpointId, mentioned, replyTo) {
         this.conversation = conversation;
         this.content = content;
         this.generation = generation;
@@ -55,8 +58,42 @@ export class Message {
         this.metadata = metadata;
         this.segments = segments;
         this.message = message;
+        this.endpointId = endpointId;
+        this.mentioned = mentioned;
+        this.replyTo = replyTo;
         this.$reply = (content) => reply(content);
         this.$replyFrom = (requester, content) => reply(content, requester);
+        this.$sendTo = (target, content) => reply(content, undefined, target);
+        this.$replyToPrivate = (content, from) => {
+            if (!sender)
+                throw new Error('Cannot $replyToPrivate: message has no sender');
+            let parent;
+            if (from === true) {
+                if (conversation.kind !== 'group' && conversation.kind !== 'channel') {
+                    throw new Error('Cannot $replyToPrivate with from=true: current conversation must be a group or channel');
+                }
+                parent = { kind: conversation.kind, id: conversation.id };
+            }
+            else if (from != null && typeof from === 'object') {
+                parent = from;
+            }
+            return reply(content, undefined, {
+                kind: 'private',
+                id: sender.id,
+                ...(parent ? { parent } : {}),
+            });
+        };
+        this.$replyToGroup = (groupId, content) => {
+            return reply(content, undefined, { kind: 'group', id: groupId });
+        };
+        this.$replyToChannel = (channelId, guildId, content, threadId) => {
+            return reply(content, undefined, {
+                kind: 'channel',
+                id: channelId,
+                parent: { kind: 'channel', id: guildId },
+                ...(threadId ? { threadId } : {}),
+            });
+        };
         Object.freeze(this);
     }
     /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
@@ -65,6 +102,47 @@ export class Message {
     }
     $reply;
     $replyFrom;
+    /**
+     * 向同 Endpoint 的另一个通道发送消息（通用）。
+     *
+     * ```ts
+     * await message.$sendTo({ kind: 'channel', id: 'ch-1', parent: { kind: 'channel', id: 'guild-1' } }, '频道通知');
+     * ```
+     */
+    $sendTo;
+    /**
+     * 私信当前消息的发送者（同 Endpoint）。
+     *
+     * @param content 消息内容
+     * @param from 会话上下文：
+     *   - `true` — 用当前群/频道作为 parent（要求当前不在私聊中）
+     *   - `{ kind, id }` — 显式指定 parent（群或子频道）
+     *   - 省略 — 直接私信
+     *
+     * ```ts
+     * await message.$replyToPrivate('直接私信');
+     * await message.$replyToPrivate('群临时私信', true);
+     * await message.$replyToPrivate('频道私信', { kind: 'channel', id: '子频道ID' });
+     * ```
+     */
+    $replyToPrivate;
+    /**
+     * 向指定群发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToGroup('67890', '群通知');
+     * ```
+     */
+    $replyToGroup;
+    /**
+     * 向指定频道/子频道发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToChannel('channel-1', 'guild-1', '频道通知');
+     * await message.$replyToChannel('channel-1', 'guild-1', '话题回复', 'thread-1');
+     * ```
+     */
+    $replyToChannel;
 }
 export function createOutboundEnvelope(request, initialPayload) {
     let payload = initialPayload;

package/lib/plugin-runtime/im/im-runtime.d.ts

@@ -1,16 +1,22 @@
-import { Scope, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { Scope, type PluginId, type SnapshotLease, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { MessageBus } from './message-bus.js';
 import { type EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
 import { type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
-import { Message, type ConversationAddress, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type SendRequest } from './contracts.js';
+import { Message, type ConversationAddress, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type MessageSenderRef, type SendRequest } from './contracts.js';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { type RuntimeInteractiveHandler } from './interactive.js';
 export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
+/** Generation-owned terminal route after interactive/command routing misses. */
+export interface IngressRoute {
+    route(message: Message, lease: SnapshotLease, requester: PluginId): Promise<boolean>;
+}
+export declare const ingressRouteToken: import("@zhin.js/plugin-runtime").Token<IngressRoute>;
 /** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
 export interface RuntimeMessageEvent {
     readonly direction: 'inbound' | 'outbound';
     readonly conversation: ConversationRef;
-    /** inbound：发送者 id。 */
-    readonly sender?: string;
+    /** inbound：发送者。 */
+    readonly sender?: MessageSenderRef;
     /** outbound：发起方插件。 */
     readonly requester?: PluginId;
     /** 预览文本，截断至 200 字。 */
@@ -26,17 +32,15 @@ export interface ImRuntimeOptions {
      */
     readonly commandPrefix?: string;
     readonly renderer?: OutboundRenderer;
+    /** Process-root ingress claim (pending interaction, authentication challenge, etc.). */
+    readonly inboundClaim?: (message: Message) => boolean | Promise<boolean>;
 }
 export declare class ImRuntime implements MessageGateway {
     #private;
     constructor(options?: ImRuntimeOptions);
     attach(snapshots: SnapshotStore): void;
-    /**
-     * Optional Host AI / fallback path after Command miss (or non-prefixed text).
-     * Return true when the message was handled (reply already sent).
-     * `requester` is the Adapter Endpoint owner (for CapabilityIngress inheritance).
-     */
-    setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
+    readonly permissionHost: import("@zhin.js/permission").PermissionHost;
+    readonly messageBus: MessageBus;
     install(resources: Scope): void;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
@@ -60,7 +64,18 @@ export declare class ImRuntime implements MessageGateway {
         readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
         readonly managementCapabilities: readonly EndpointManagementCapability[];
     }[];
-    getEndpoint(adapter: string, endpointId: string): {
+    /**
+     * Console `GET /api/stats` 同源计数：非 root 插件节点 + AdapterIndex endpoints。
+     * 供命令 / 状态卡等在 Plugin Runtime 下读取（legacy `root.adapters` / `root.children` 已不存在）。
+     */
+    inventory(): Readonly<{
+        plugins: number;
+        endpoints: {
+            readonly total: number;
+            readonly online: number;
+        };
+    }>;
+    getEndpoint(adapter: string, endpointKey: string): {
         readonly name: string;
         readonly adapter: string;
         readonly connected: boolean;
@@ -70,7 +85,7 @@ export declare class ImRuntime implements MessageGateway {
     } | null;
     sendEndpointMessage(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly conversation: ConversationAddress;
         readonly content: unknown;
     }): Promise<{
@@ -79,7 +94,7 @@ export declare class ImRuntime implements MessageGateway {
     /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
     addEndpointReaction(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
         readonly emoji: string;
@@ -88,7 +103,7 @@ export declare class ImRuntime implements MessageGateway {
     }): Promise<string | null>;
     removeEndpointReaction(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
         readonly reactionId: string;
@@ -96,32 +111,27 @@ export declare class ImRuntime implements MessageGateway {
     /** Activity-feedback autoRemove: recall a previously sent status message. */
     recallEndpointMessage(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
     }): Promise<void>;
     editEndpointMessage(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
         readonly content: unknown;
     }): Promise<string | null>;
     setEndpointTyping(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly conversation: ConversationRef;
         readonly active?: boolean;
     }): Promise<void>;
-    /**
-     * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
-     * @deprecated Host callers should use `getEndpointManagement()`.
-     */
-    getLiveEndpoint(adapter: string, endpointId: string): unknown | null;
     /**
      * Narrow Host seam for Console social/group management. An empty object means
      * the Endpoint exists but implements no management operations; null means it
      * cannot be resolved.
      */
-    getEndpointManagement(adapter: string, endpointId: string): EndpointManagement | null;
+    getEndpointManagement(adapter: string, endpointKey: string): EndpointManagement | null;
 }

package/lib/plugin-runtime/im/im-runtime.js

@@ -1,4 +1,6 @@
 import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
+import { createPermissionHost, permissionHostToken } from '@zhin.js/permission';
+import { MessageBus, messageBusToken } from './message-bus.js';
 import { adapterFeatureId, isAdapterIndex, resolveEndpointControl, resolveEndpointManagement, } from '@zhin.js/adapter';
 import { formatLegacyMessageRef, isDeliveryReceipt, } from '@zhin.js/im-contract';
 import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
@@ -12,6 +14,7 @@ import { keyboardFallbackStore } from '../../built/interactive-segments/fallback
 import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveConversationKey, } from './interactive.js';
 const logger = getLogger('im');
 export const messageGatewayToken = createToken('zhin.im.message-gateway');
+export const ingressRouteToken = createToken('zhin.im.ingress-route');
 export const messagePreviewLimit = 200;
 export class ImRuntime {
     #dispatcher;
@@ -19,12 +22,13 @@ export class ImRuntime {
     #messageListeners = new Set();
     #interactiveHandlers = [];
     #snapshots;
-    #unmatchedHandler;
+    #inboundClaim;
     constructor(options = {}) {
         this.#dispatcher = new MessageDispatcher(options.commandPrefix === undefined
             ? defaultCommandPrefixResolver
             : () => options.commandPrefix ?? '');
         this.#renderer = options.renderer ?? new OutboundRenderer();
+        this.#inboundClaim = options.inboundClaim;
     }
     attach(snapshots) {
         if (this.#snapshots && this.#snapshots !== snapshots) {
@@ -32,16 +36,12 @@ export class ImRuntime {
         }
         this.#snapshots = snapshots;
     }
-    /**
-     * Optional Host AI / fallback path after Command miss (or non-prefixed text).
-     * Return true when the message was handled (reply already sent).
-     * `requester` is the Adapter Endpoint owner (for CapabilityIngress inheritance).
-     */
-    setUnmatchedHandler(handler) {
-        this.#unmatchedHandler = handler;
-    }
+    permissionHost = createPermissionHost();
+    messageBus = new MessageBus();
     install(resources) {
         resources.provide(messageGatewayToken, this);
+        resources.provide(permissionHostToken, this.permissionHost);
+        resources.provide(messageBusToken, this.messageBus);
     }
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
@@ -82,48 +82,58 @@ export class ImRuntime {
             const adapter = conversation.endpoint.id;
             const requester = requireAdapters(lease.value).owner(adapter);
             logger.debug(formatCompact({
-                op: 'im_inbound_receive',
-                adapter: String(adapter).split('\0').pop() ?? String(adapter),
-                conversation: formatConversationLog(conversation),
-                sender: input.sender,
-                id: input.message?.id,
+                op: 'receive',
+                conv: formatConversationLog(conversation),
+                sender: `${input.sender?.name || 'undefined'}(${input.sender?.id || 'undefined'})`,
                 preview: truncatePreview(input.content),
-                segments: input.segments?.length,
-                generation: lease.value.generation,
             }));
-            const message = new Message(conversation, input.content, lease.value.generation, (content, replyRequester = requester) => {
+            const message = new Message(conversation, input.content, lease.value.generation, (content, replyRequester = requester, targetConversation) => {
                 if (!active)
                     throw new Error('Message reply scope has ended');
+                const effectiveConversation = targetConversation
+                    ? { endpoint: conversation.endpoint, ...targetConversation }
+                    : conversation;
                 return this.#sendWithSnapshot({
-                    conversation,
+                    conversation: effectiveConversation,
                     requester: replyRequester,
                     content,
+                    incoming: {
+                        sender: input.sender,
+                        content: input.content,
+                        segments: input.segments,
+                        messageId: input.message?.id,
+                        timestamp: Date.now(),
+                        endpointId: input.endpointId,
+                        mentioned: input.mentioned,
+                    },
                 }, lease.value);
-            }, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.message);
+            }, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.message, input.endpointId, input.mentioned, input.replyTo);
             let result = Object.freeze({ matched: false });
-            await runMiddleware(lease.value, message, async () => {
-                result = await this.#dispatchInteractive(message, requester)
-                    ?? await this.#dispatcher.dispatch(message, lease.value);
-                if (!result.matched && this.#unmatchedHandler) {
-                    logger.debug(formatCompact({
-                        op: 'im_inbound_unmatched_handler',
-                        conversation: formatConversationLog(conversation),
-                        id: input.message?.id,
-                    }));
-                    const handled = await this.#unmatchedHandler(message, lease.value, requester);
-                    if (handled) {
-                        result = Object.freeze({ matched: true, command: 'ai', owner: requester });
+            const claimed = await this.#inboundClaim?.(message) === true;
+            if (claimed) {
+                result = Object.freeze({ matched: true, command: 'interaction', owner: requester });
+            }
+            else {
+                await runMiddleware(lease.value, message, async () => {
+                    result = await this.#dispatchInteractive(message, requester)
+                        ?? await this.#dispatcher.dispatch(message, lease.value);
+                    const ingressRoute = resolveIngressRoute(lease.value);
+                    if (!result.matched && ingressRoute) {
+                        logger.debug(formatCompact({ op: 'unmatched', conv: formatConversationLog(conversation) }));
+                        const handled = await ingressRoute.route(message, lease, requester);
+                        if (handled) {
+                            result = Object.freeze({ matched: true, command: 'ai', owner: requester });
+                        }
                     }
-                }
-            }, 'inbound');
-            logger.debug(formatCompact({
-                op: 'im_inbound_done',
-                conversation: formatConversationLog(conversation),
-                id: input.message?.id,
-                matched: result.matched,
-                command: result.command,
-                owner: result.owner,
-            }));
+                }, 'inbound');
+            }
+            if (result.matched) {
+                logger.debug(formatCompact({
+                    op: 'dispatched',
+                    conv: formatConversationLog(conversation),
+                    command: result.command,
+                }));
+            }
             this.#emitMessage({
                 direction: 'inbound',
                 conversation,
@@ -172,12 +182,42 @@ export class ImRuntime {
             return Object.freeze([]);
         }
     }
-    getEndpoint(adapter, endpointId) {
+    /**
+     * Console `GET /api/stats` 同源计数：非 root 插件节点 + AdapterIndex endpoints。
+     * 供命令 / 状态卡等在 Plugin Runtime 下读取（legacy `root.adapters` / `root.children` 已不存在）。
+     */
+    inventory() {
+        try {
+            const lease = this.#acquire();
+            try {
+                const plugins = [...lease.value.tree.values()]
+                    .filter((node) => node.parent !== undefined).length;
+                const endpoints = requireAdapters(lease.value).describe();
+                return Object.freeze({
+                    plugins,
+                    endpoints: Object.freeze({
+                        total: endpoints.length,
+                        online: endpoints.filter((endpoint) => endpoint.status === 'online').length,
+                    }),
+                });
+            }
+            finally {
+                lease.release();
+            }
+        }
+        catch {
+            return Object.freeze({
+                plugins: 0,
+                endpoints: Object.freeze({ total: 0, online: 0 }),
+            });
+        }
+    }
+    getEndpoint(adapter, endpointKey) {
         try {
             const lease = this.#acquire();
             try {
                 const index = requireAdapters(lease.value);
-                const id = index.resolve(adapter, endpointId);
+                const id = index.resolve(adapter, endpointKey);
                 if (!id)
                     return null;
                 const row = index.describe().find((item) => item.id === id);
@@ -206,7 +246,7 @@ export class ImRuntime {
         const lease = this.#acquire();
         try {
             const index = requireAdapters(lease.value);
-            const resolved = index.resolve(input.adapter, input.endpointId);
+            const resolved = index.resolve(input.adapter, input.endpointKey);
             if (!resolved)
                 throw new Error('endpoint not found');
             const requester = index.owner(resolved);
@@ -228,34 +268,34 @@ export class ImRuntime {
     }
     /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
     async addEndpointReaction(input) {
-        const control = this.#liveEndpointControl(input.adapter, input.endpointId);
+        const control = this.#liveEndpointControl(input.adapter, input.endpointKey);
         return control?.addReaction?.(legacyMessageTarget(input.message, input.messageId), input.emoji, {
             sceneType: input.sceneType,
             channelId: input.channelId,
         }) ?? null;
     }
     async removeEndpointReaction(input) {
-        await this.#liveEndpointControl(input.adapter, input.endpointId)
+        await this.#liveEndpointControl(input.adapter, input.endpointKey)
             ?.removeReaction?.(legacyMessageTarget(input.message, input.messageId), input.reactionId);
     }
     /** Activity-feedback autoRemove: recall a previously sent status message. */
     async recallEndpointMessage(input) {
-        await this.#liveEndpointControl(input.adapter, input.endpointId)
+        await this.#liveEndpointControl(input.adapter, input.endpointKey)
             ?.recall?.(legacyMessageTarget(input.message, input.messageId));
     }
     async editEndpointMessage(input) {
-        return this.#liveEndpointControl(input.adapter, input.endpointId)
+        return this.#liveEndpointControl(input.adapter, input.endpointKey)
             ?.edit?.(legacyMessageTarget(input.message, input.messageId), input.content) ?? null;
     }
     async setEndpointTyping(input) {
-        await this.#liveEndpointControl(input.adapter, input.endpointId)
+        await this.#liveEndpointControl(input.adapter, input.endpointKey)
             ?.typing?.(input.conversation, input.active);
     }
-    #liveEndpoint(adapter, endpointId) {
+    #liveEndpoint(adapter, endpointKey) {
         try {
             const lease = this.#acquire();
             try {
-                const endpoint = requireAdapters(lease.value).instance(adapter, endpointId);
+                const endpoint = requireAdapters(lease.value).instance(adapter, endpointKey);
                 return endpoint ?? null;
             }
             finally {
@@ -266,24 +306,17 @@ export class ImRuntime {
             return null;
         }
     }
-    #liveEndpointControl(adapter, endpointId) {
-        const endpoint = this.#liveEndpoint(adapter, endpointId);
+    #liveEndpointControl(adapter, endpointKey) {
+        const endpoint = this.#liveEndpoint(adapter, endpointKey);
         return resolveEndpointControl(endpoint) ?? null;
     }
-    /**
-     * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
-     * @deprecated Host callers should use `getEndpointManagement()`.
-     */
-    getLiveEndpoint(adapter, endpointId) {
-        return this.#liveEndpoint(adapter, endpointId);
-    }
     /**
      * Narrow Host seam for Console social/group management. An empty object means
      * the Endpoint exists but implements no management operations; null means it
      * cannot be resolved.
      */
-    getEndpointManagement(adapter, endpointId) {
-        const endpoint = this.#liveEndpoint(adapter, endpointId);
+    getEndpointManagement(adapter, endpointKey) {
+        const endpoint = this.#liveEndpoint(adapter, endpointKey);
         if (!endpoint)
             return null;
         return resolveEndpointManagement(endpoint) ?? Object.freeze({});
@@ -292,7 +325,7 @@ export class ImRuntime {
         const adapter = request.conversation.endpoint.id;
         let initialPayload;
         try {
-            const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
+            const rendered = await this.#renderer.render(request.content, request.requester, snapshot, request.conversation, request.incoming);
             initialPayload = await prepareOutboundPayload(rendered, request.conversation, snapshot);
         }
         catch {
@@ -371,6 +404,14 @@ export class ImRuntime {
             : undefined;
     }
 }
+function resolveIngressRoute(snapshot) {
+    const candidate = snapshot.resources.get(snapshot.root)?.get(ingressRouteToken.id);
+    return candidate
+        && typeof candidate === 'object'
+        && typeof candidate.route === 'function'
+        ? candidate
+        : undefined;
+}
 function requireAdapters(snapshot) {
     const projection = snapshot.projections.get(adapterFeatureId);
     if (!isAdapterIndex(projection)) {

package/lib/plugin-runtime/im/index.d.ts

@@ -1,6 +1,8 @@
 export * from './contracts.js';
 export * from './im-runtime.js';
 export * from './interactive.js';
+export * from './message-bus.js';
 export * from './message-dispatcher.js';
 export * from './outbound-renderer.js';
 export * from './outbound-segments.js';
+export * from './service-tokens.js';

package/lib/plugin-runtime/im/index.js

@@ -1,6 +1,8 @@
 export * from './contracts.js';
 export * from './im-runtime.js';
 export * from './interactive.js';
+export * from './message-bus.js';
 export * from './message-dispatcher.js';
 export * from './outbound-renderer.js';
 export * from './outbound-segments.js';
+export * from './service-tokens.js';

package/lib/plugin-runtime/im/message-bus.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MessageBus — 独立于 Plugin 的 IM 生命周期事件总线。
+ *
+ * 覆盖 Plugin.Lifecycle 中关键 IM 事件，供 Scope+Token 路径消费。
+ * 遗留 Plugin.emit 通过短暂双写桥接（迁移窗口）。
+ */
+import type { DeliveryReceipt } from '@zhin.js/im-contract';
+import type { Message, OutboundEnvelope, SendContent } from './contracts.js';
+export interface EndpointEvent {
+    readonly adapter: string;
+    readonly endpointKey: string;
+    readonly error?: Error;
+}
+export interface MessageBusEventMap {
+    'message.receive': [message: Message];
+    'before.sendMessage': [envelope: OutboundEnvelope];
+    'message.send': [payload: {
+        adapter: string;
+        endpointKey: string;
+        content: SendContent;
+        receipt: DeliveryReceipt;
+    }];
+    'endpoint.connect': [event: EndpointEvent];
+    'endpoint.disconnect': [event: EndpointEvent];
+    'endpoint.error': [event: EndpointEvent];
+}
+export type MessageBusEventName = keyof MessageBusEventMap;
+export declare class MessageBus {
+    private readonly emitter;
+    constructor();
+    on<E extends MessageBusEventName>(event: E, listener: (...args: MessageBusEventMap[E]) => void): () => void;
+    once<E extends MessageBusEventName>(event: E, listener: (...args: MessageBusEventMap[E]) => void): () => void;
+    emit<E extends MessageBusEventName>(event: E, ...args: MessageBusEventMap[E]): void;
+    off<E extends MessageBusEventName>(event: E, listener: (...args: MessageBusEventMap[E]) => void): void;
+    listenerCount(event: MessageBusEventName): number;
+    removeAllListeners(event?: MessageBusEventName): void;
+}
+export declare const messageBusToken: import("@zhin.js/plugin-runtime").Token<MessageBus>;

package/lib/plugin-runtime/im/message-bus.js

@@ -0,0 +1,40 @@
+/**
+ * MessageBus — 独立于 Plugin 的 IM 生命周期事件总线。
+ *
+ * 覆盖 Plugin.Lifecycle 中关键 IM 事件，供 Scope+Token 路径消费。
+ * 遗留 Plugin.emit 通过短暂双写桥接（迁移窗口）。
+ */
+import { EventEmitter } from 'node:events';
+import { createToken } from '@zhin.js/plugin-runtime';
+export class MessageBus {
+    emitter = new EventEmitter();
+    constructor() {
+        this.emitter.setMaxListeners(50);
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return () => this.emitter.off(event, listener);
+    }
+    once(event, listener) {
+        this.emitter.once(event, listener);
+        return () => this.emitter.off(event, listener);
+    }
+    emit(event, ...args) {
+        this.emitter.emit(event, ...args);
+    }
+    off(event, listener) {
+        this.emitter.off(event, listener);
+    }
+    listenerCount(event) {
+        return this.emitter.listenerCount(event);
+    }
+    removeAllListeners(event) {
+        if (event) {
+            this.emitter.removeAllListeners(event);
+        }
+        else {
+            this.emitter.removeAllListeners();
+        }
+    }
+}
+export const messageBusToken = createToken('zhin.im.message-bus');