@zhin.js/core 1.5.1 → 1.5.4

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

@@ -1,6 +1,8 @@
 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 { formatLegacyConversationRef, formatLegacyMessageRef, isDeliveryReceipt, } from '@zhin.js/im-contract';
+import { formatLegacyMessageRef, isDeliveryReceipt, } from '@zhin.js/im-contract';
 import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
 import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
 import { Message, createOutboundEnvelope, } from './contracts.js';
@@ -9,9 +11,10 @@ import { OutboundRenderer } from './outbound-renderer.js';
 import { applyOutboundInteractivePolicy, normalizeOutboundPayload, resolveOutboundInteractivePolicy, resolveOutboundMediaPolicy, } from './outbound-segments.js';
 import { assertCanonicalSegments } from '../../built/segment-contract/assert.js';
 import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
-import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveChannelKey, } from './interactive.js';
+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 最长匹配；返回注销函数）。
@@ -78,64 +78,68 @@ export class ImRuntime {
         const lease = this.#acquire();
         let active = true;
         try {
-            const requester = requireAdapters(lease.value).owner(input.adapter);
+            const conversation = input.conversation;
+            const adapter = conversation.endpoint.id;
+            const requester = requireAdapters(lease.value).owner(adapter);
             logger.debug(formatCompact({
-                op: 'im_inbound_receive',
-                adapter: String(input.adapter).split('\0').pop() ?? String(input.adapter),
-                target: input.target,
-                sender: input.sender,
-                id: input.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(input.adapter, input.target, 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({
-                    adapter: input.adapter,
-                    ...(input.conversation ? { conversation: input.conversation } : {}),
-                    target: input.target,
+                    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.id ?? input.message?.id, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.conversation, 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',
-                        target: input.target,
-                        id: input.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',
-                target: input.target,
-                id: input.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',
-                adapter: input.adapter,
-                target: input.target,
+                conversation,
                 ...(input.sender !== undefined ? { sender: input.sender } : {}),
-                ...(channelTypeOf(input.target)
-                    ? { channelType: channelTypeOf(input.target) }
-                    : {}),
                 contentPreview: previewText(input.content),
-                ...(input.id ?? input.message?.id
-                    ? { messageId: input.id ?? input.message?.id }
-                    : {}),
+                ...(input.message?.id ? { messageId: input.message.id } : {}),
                 timestamp: Date.now(),
             });
             return result;
@@ -178,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);
@@ -212,22 +246,19 @@ export class ImRuntime {
         const lease = this.#acquire();
         try {
             const index = requireAdapters(lease.value);
-            const capabilityId = index.resolve(input.adapter, input.endpointId);
-            if (!capabilityId)
+            const resolved = index.resolve(input.adapter, input.endpointKey);
+            if (!resolved)
                 throw new Error('endpoint not found');
-            const target = input.conversation
-                ? formatLegacyConversationRef(input.conversation)
-                : composeSendTarget(input.channelType ?? '', input.channelId ?? '');
-            if (!target)
-                throw new TypeError('conversation or channelId is required');
+            const requester = index.owner(resolved);
+            const conversation = {
+                endpoint: { id: String(resolved), adapter: String(requester) },
+                ...input.conversation,
+            };
             const content = normalizeConsoleContent(input.content);
             const result = await this.#sendWithSnapshot({
-                adapter: capabilityId,
-                ...(input.conversation ? { conversation: input.conversation } : {}),
-                target,
-                requester: index.owner(capabilityId),
+                conversation,
+                requester,
                 content,
-                ...(input.parent ? { parent: input.parent } : {}),
             }, lease.value);
             return { messageId: result.message?.id ?? result.legacyMessageId ?? '' };
         }
@@ -237,39 +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) {
-        const target = input.conversation
-            ? formatLegacyConversationRef(input.conversation)
-            : input.target;
-        if (!target)
-            throw new TypeError('conversation or target is required');
-        await this.#liveEndpointControl(input.adapter, input.endpointId)
-            ?.typing?.(target, input.active);
+        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 {
@@ -280,44 +306,35 @@ 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({});
     }
     async #sendWithSnapshot(request, snapshot) {
+        const adapter = request.conversation.endpoint.id;
         let initialPayload;
         try {
-            const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
-            initialPayload = await prepareOutboundPayload(rendered, request, snapshot);
+            const rendered = await this.#renderer.render(request.content, request.requester, snapshot, request.conversation, request.incoming);
+            initialPayload = await prepareOutboundPayload(rendered, request.conversation, snapshot);
         }
         catch {
             return rejectedReceipt('outbound_payload_rejected');
         }
         const envelope = createOutboundEnvelope({
-            adapter: request.adapter,
-            ...(request.conversation ? { conversation: request.conversation } : {}),
-            target: request.target,
+            conversation: request.conversation,
             requester: request.requester,
             generation: snapshot.generation,
-            ...(request.parent ? { parent: request.parent } : {}),
         }, initialPayload);
         let terminalEntered = false;
         let receipt;
@@ -326,20 +343,16 @@ export class ImRuntime {
                 terminalEntered = true;
                 let payload;
                 try {
-                    // Middleware may replace a payload with legacy/wire segments. Normalize
-                    // again at the transport boundary so it cannot bypass core policy.
-                    payload = await prepareOutboundPayload(envelope.payload, request, snapshot, true);
+                    payload = await prepareOutboundPayload(envelope.payload, request.conversation, snapshot, true);
                 }
                 catch {
                     receipt = rejectedReceipt('outbound_payload_rejected');
                     return;
                 }
                 try {
-                    const result = await requireAdapters(snapshot).send(request.adapter, {
-                        target: request.target,
-                        ...(request.conversation ? { conversation: request.conversation } : {}),
+                    const result = await requireAdapters(snapshot).send(adapter, {
+                        conversation: request.conversation,
                         payload,
-                        ...(request.parent ? { parent: request.parent } : {}),
                     });
                     receipt = receiptFromEndpointResult(result);
                 }
@@ -349,8 +362,7 @@ export class ImRuntime {
                 if (receipt?.status === 'sent') {
                     this.#emitMessage({
                         direction: 'outbound',
-                        adapter: request.adapter,
-                        target: request.target,
+                        conversation: request.conversation,
                         requester: request.requester,
                         contentPreview: previewText(payload),
                         ...(receipt.message?.id || receipt.legacyMessageId
@@ -362,8 +374,6 @@ export class ImRuntime {
             }, 'outbound');
         }
         catch {
-            // If a middleware fails after the terminal, the endpoint has already
-            // produced its receipt (and, for a real send, its event). Keep that fact.
             return receipt ?? failedReceipt('outbound_middleware_failed');
         }
         if (!terminalEntered)
@@ -394,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)) {
@@ -423,18 +441,17 @@ function legacyMessageTarget(message, messageId) {
         return messageId;
     throw new TypeError('message or messageId is required');
 }
-async function prepareOutboundPayload(rendered, request, snapshot, finalizeInteractive = false) {
-    const directHtml = isDirectHtmlConsumer(snapshot, request.adapter);
+async function prepareOutboundPayload(rendered, conversation, snapshot, finalizeInteractive = false) {
+    const adapter = conversation.endpoint.id;
+    const directHtml = isDirectHtmlConsumer(snapshot, adapter);
     let payload = directHtml
         ? rendered
         : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot), {
-            mediaPolicy: resolveOutboundMediaPolicy(request.adapter, snapshot),
+            mediaPolicy: resolveOutboundMediaPolicy(adapter, snapshot),
         });
     if (finalizeInteractive) {
-        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(request.adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveChannelKey(String(request.adapter), request.target), map));
+        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveConversationKey(conversation), map));
     }
-    // Segment arrays crossing the adapter boundary are canonical after every
-    // middleware transform. Direct html consumers retain their explicit wire API.
     if (!directHtml && Array.isArray(payload))
         assertCanonicalSegments(payload);
     return payload;
@@ -490,18 +507,6 @@ function failedReceipt(code, retryable = false) {
         }),
     });
 }
-/**
- * Build Adapter send target. If channelId already carries a scene prefix
- * (`private:uid` / `group:gid`), do not double-prefix.
- */
-function composeSendTarget(channelType, channelId) {
-    const id = channelId.trim();
-    if (!id)
-        return channelType || '';
-    if (/^(private|group|channel|direct|c2c|temp):/iu.test(id))
-        return id;
-    return channelType ? `${channelType}:${id}` : id;
-}
 /** `@zhin.js/adapter-icqq` → `icqq`；非 adapter 包名原样返回。 */
 function adapterTypeName(packageName) {
     if (!packageName)
@@ -528,10 +533,14 @@ function normalizeConsoleContent(content) {
         return content;
     return String(content);
 }
-/** target 前缀场景：`group:123` → `group`；无前缀返回 undefined。 */
-function channelTypeOf(target) {
-    const match = /^([a-z0-9-]+):/iu.exec(target);
-    return match?.[1];
+/** 日志用会话摘要（`kind:id@parentKind:parentId#threadId`），不拼 legacy target。 */
+function formatConversationLog(conversation) {
+    const base = `${conversation.kind}:${conversation.id}`;
+    const parent = conversation.parent
+        ? `@${conversation.parent.kind}:${conversation.parent.id}`
+        : '';
+    const thread = conversation.threadId ? `#${conversation.threadId}` : '';
+    return `${base}${parent}${thread}`;
 }
 /** 消息内容 → 预览文本（截断 200 字）；wire 段取 `data.text`，其余段记 `[type]`。 */
 function previewText(content) {

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/interactive.d.ts

@@ -1,3 +1,4 @@
+import type { ConversationRef } from '@zhin.js/im-contract';
 import type { Message } from './contracts.js';
 /**
  * Plugin Runtime IM 管线的 interactive action 回跳（旧轨
@@ -14,8 +15,8 @@ export interface RegisteredRuntimeInteractiveHandler {
     readonly prefix: string;
     readonly handler: RuntimeInteractiveHandler;
 }
-/** 频道键：出站降级写入与入站回跳读取共用（`adapter~target`）。 */
-export declare function runtimeInteractiveChannelKey(adapter: string, target: string): string;
+/** 频道键：出站降级写入与入站回跳读取共用（由 ConversationRef 派生，稳定即可）。 */
+export declare function runtimeInteractiveConversationKey(conversation: ConversationRef): string;
 /** prefix 最长匹配（与旧轨 findHandler 一致）。 */
 export declare function findRuntimeInteractiveHandler(handlers: readonly RegisteredRuntimeInteractiveHandler[], payload: string): RuntimeInteractiveHandler | undefined;
 /**

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

@@ -1,8 +1,13 @@
 import { resolvePayloadFromText } from '../../built/interactive-segments/action.js';
 import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
-/** 频道键：出站降级写入与入站回跳读取共用（`adapter~target`）。 */
-export function runtimeInteractiveChannelKey(adapter, target) {
-    return `${adapter}~${target}`;
+/** 频道键：出站降级写入与入站回跳读取共用（由 ConversationRef 派生，稳定即可）。 */
+export function runtimeInteractiveConversationKey(conversation) {
+    const base = `${String(conversation.endpoint.id)}~${conversation.kind}:${conversation.id}`;
+    const parent = conversation.parent
+        ? `@${conversation.parent.kind}:${conversation.parent.id}`
+        : '';
+    const thread = conversation.threadId ? `#${conversation.threadId}` : '';
+    return `${base}${parent}${thread}`;
 }
 /** prefix 最长匹配（与旧轨 findHandler 一致）。 */
 export function findRuntimeInteractiveHandler(handlers, payload) {
@@ -27,7 +32,7 @@ export function resolveRuntimeInteractivePayload(message) {
     const raw = message.content.trim();
     if (!raw)
         return undefined;
-    return resolvePayloadFromText(raw, keyboardFallbackStore.mapFor(runtimeInteractiveChannelKey(String(message.adapter), message.target)));
+    return resolvePayloadFromText(raw, keyboardFallbackStore.mapFor(runtimeInteractiveConversationKey(message.conversation)));
 }
 function actionPayloadFromSegments(segments) {
     for (const seg of segments ?? []) {

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');