@zhin.js/core 1.5.13 → 1.5.15

package/lib/adapter.d.ts

@@ -41,9 +41,10 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
     /** 当前正在处理的消息数 */
     get pendingMessages(): number;
     /**
-     * 构造函数
+     * 创建一个适配器运行实例。
+     * @param plugin 拥有该适配器的插件实例
      * @param name 适配器名称（如 'process'、'qq' 等）
-     * @param endpointFactory Bot工厂函数或构造器
+     * @param config Endpoint 配置列表
      */
     constructor(plugin: Plugin, name: keyof Plugin.Contexts, config: Adapter.EndpointConfig<R>[]);
     /** 入站消息管线（替代 emit override 的隐式管线） */

package/lib/adapter.js

@@ -55,9 +55,10 @@ export class Adapter extends EventEmitter {
         return this.#pendingMessages;
     }
     /**
-     * 构造函数
+     * 创建一个适配器运行实例。
+     * @param plugin 拥有该适配器的插件实例
      * @param name 适配器名称（如 'process'、'qq' 等）
-     * @param endpointFactory Bot工厂函数或构造器
+     * @param config Endpoint 配置列表
      */
     constructor(plugin, name, config) {
         super();

package/lib/built/dispatcher.d.ts

@@ -80,7 +80,7 @@ export type AITriggerMatcher = (message: Message<any>) => {
  */
 export type GroupPassiveContextHandler = (message: Message<any>) => MaybePromise<void>;
 export type GuardrailMiddleware = MessageMiddleware<RegisteredAdapter>;
-/** @alias OutboundReplySource：出站回复来源（指令 / AI） */
+/** Backward-compatible name for the command or AI outbound reply source. */
 export type ReplySource = OutboundReplySource;
 /** replyWithPolish 可选参数 */
 export interface ReplyWithPolishOptions {

package/lib/feature/handler.d.ts

@@ -1,10 +1,52 @@
 /** Authoring API for Handler Feature — implementation in `@zhin.js/handler`. */
-export { defineHandler, parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, type HandlerEventMap, type HandlerDefinition, type HandlerDescriptor, type HandlerContext, type HandlerDispatchOptions, } from '@zhin.js/handler';
+export { parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, type HandlerEventMap, type HandlerDefinition, type HandlerDescriptor, type HandlerContext, type HandlerDispatchOptions, } from '@zhin.js/handler';
+import { type HandlerContext, type HandlerDefinition, type HandlerEventMap } from '@zhin.js/handler';
 import type { Plugin } from '../plugin.js';
+import type { Message } from '../plugin-runtime/im/contracts.js';
+import type { Notice } from '../notice.js';
+import type { Request } from '../request.js';
+import type { SystemEvent } from '../system-event.js';
+import type { AdapterClient, AdapterEvents, EndpointEvent, EndpointIdentity, PlatformEvent, RegisteredAdapterName } from '@zhin.js/adapter';
 type KnownKeys<T> = {
     [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
 };
 declare module '@zhin.js/handler' {
-    interface HandlerEventMap extends KnownKeys<Plugin.Lifecycle> {
+    interface HandlerEventMap extends KnownKeys<Omit<Plugin.Lifecycle, 'message.receive' | 'notice.receive' | 'request.receive' | 'system.receive'>> {
+        'message.receive': [event: EndpointEvent<Message>];
+        'notice.receive': [event: EndpointEvent<Notice>];
+        'request.receive': [event: EndpointEvent<Request>];
+        'system.receive': [event: EndpointEvent<SystemEvent>];
+        'platform.receive': [event: EndpointEvent<PlatformEvent>];
     }
 }
+type NativeEventName<TAdapter extends RegisteredAdapterName> = Extract<keyof AdapterEvents<TAdapter>, string>;
+/** Fully inferred native platform event exposed to plugin handlers. */
+export interface ClientHandlerEvent<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter> = NativeEventName<TAdapter>> {
+    readonly name: TName;
+    readonly event: AdapterEvents<TAdapter>[TName];
+    readonly endpoint: EndpointIdentity;
+    readonly client: AdapterClient<TAdapter>;
+}
+export interface ClientHandlerOptions<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter>> {
+    readonly adapter: TAdapter;
+    readonly event: TName;
+    handle(this: HandlerContext, event: ClientHandlerEvent<TAdapter, TName>): void | Promise<void>;
+}
+export interface ClientHandlerWildcardEvent<TAdapter extends RegisteredAdapterName> {
+    readonly name: string;
+    readonly event: unknown;
+    readonly endpoint: EndpointIdentity;
+    readonly client: AdapterClient<TAdapter>;
+}
+export interface ClientHandlerWildcardOptions<TAdapter extends RegisteredAdapterName> {
+    readonly adapter: TAdapter;
+    readonly event: '*';
+    handle(this: HandlerContext, event: ClientHandlerWildcardEvent<TAdapter>): void | Promise<void>;
+}
+export declare function defineHandler<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter>>(options: ClientHandlerOptions<TAdapter, TName>): Readonly<HandlerDefinition<'platform.receive'>>;
+/** Handle every native event from one Client without pretending unknown payloads are typed. */
+export declare function defineHandler<TAdapter extends RegisteredAdapterName>(options: ClientHandlerWildcardOptions<TAdapter>): Readonly<HandlerDefinition<'platform.receive'>>;
+export declare function defineHandler<K extends keyof HandlerEventMap & string>(options: {
+    readonly event: K;
+    handle(this: HandlerContext, ...args: HandlerEventMap[K] extends unknown[] ? HandlerEventMap[K] : unknown[]): void | Promise<void>;
+}): Readonly<HandlerDefinition<K>>;

package/lib/feature/handler.js

@@ -1,2 +1,26 @@
 /** Authoring API for Handler Feature — implementation in `@zhin.js/handler`. */
-export { defineHandler, parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, } from '@zhin.js/handler';
+export { parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, } from '@zhin.js/handler';
+import { defineHandler as defineHandlerFeature, } from '@zhin.js/handler';
+export function defineHandler(options) {
+    if (!('adapter' in options) || typeof options.adapter !== 'string') {
+        return defineHandlerFeature(options);
+    }
+    const adapter = options.adapter;
+    const expectedName = options.event === '*' ? undefined : options.event;
+    return defineHandlerFeature({
+        event: 'platform.receive',
+        async handle(source) {
+            if (source.endpoint.adapter !== adapter)
+                return;
+            if (expectedName !== undefined && source.payload.name !== expectedName)
+                return;
+            const event = Object.freeze({
+                name: source.payload.name,
+                event: source.payload.event,
+                endpoint: source.endpoint,
+                client: source.client,
+            });
+            await options.handle.call(this, event);
+        },
+    });
+}

package/lib/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Canonical IM messages, Endpoints, rendering, and plugin-facing core types.
+ * @module @zhin.js/core
+ */
 export * from './endpoint.js';
 export * from './endpoint-capabilities.js';
 export * from './plugin.js';
@@ -13,7 +17,6 @@ export * from './side-event/index.js';
 export * from './schema-interaction.js';
 export type * from '@zhin.js/interaction';
 export * from './types.js';
-export * from './agent-prompt.js';
 export * from './utils.js';
 export * from './errors.js';
 export * from './built/config.js';

package/lib/index.js

@@ -1,3 +1,7 @@
+/**
+ * Canonical IM messages, Endpoints, rendering, and plugin-facing core types.
+ * @module @zhin.js/core
+ */
 // ── Core 类模块 ──────────────────────────────────────────────────────
 export * from './endpoint.js';
 export * from './endpoint-capabilities.js';
@@ -13,7 +17,6 @@ export * from './system-event.js';
 export * from './side-event/index.js';
 export * from './schema-interaction.js';
 export * from './types.js';
-export * from './agent-prompt.js';
 export * from './utils.js';
 export * from './errors.js';
 // ── Built 模块 ──────────────────────────────────────────────────────

package/lib/message.d.ts

@@ -49,6 +49,7 @@ export interface MessageBase {
  * 完整消息类型，支持扩展
  */
 export type Message<T extends object = {}> = MessageBase & T;
+/** @internal Legacy static helpers; not part of Agent resource authoring. */
 export declare namespace Message {
     /**
      * 工具方法：合并自定义字段与基础消息结构

package/lib/message.js

@@ -1,4 +1,5 @@
 import { isActionMessage as isActionMessageImpl } from "./built/interactive-segments/action.js";
+/** @internal Legacy static helpers; not part of Agent resource authoring. */
 export var Message;
 (function (Message) {
     /**

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

@@ -81,10 +81,14 @@ export interface OutboundEnvelope {
     readonly requester: PluginId;
     readonly generation: number;
     readonly payload: unknown;
+    /** Native platform Client for the Endpoint selected by `conversation`. */
+    readonly $client: unknown;
+    /** Literal adapter name used to validate adapter-bound middleware. */
+    readonly clientAdapter?: string;
     replace(payload: unknown): void;
 }
-export interface MessageGateway {
-    receive(input: IncomingMessage): Promise<MessageDispatchResult>;
+/** @public Stable IM gateway contract resolved through `outboundMessageToken`. */
+export interface OutboundMessageService {
     send(request: SendRequest): Promise<DeliveryReceipt>;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
@@ -100,6 +104,7 @@ export interface MessageDispatchResult {
     readonly value?: unknown;
 }
 export declare class Message {
+    #private;
     readonly conversation: ConversationRef;
     readonly content: string;
     readonly generation: number;
@@ -117,6 +122,8 @@ export declare class Message {
     readonly replyTo?: {
         readonly id: string;
     } | undefined;
+    readonly clientAdapter?: string | undefined;
+    /** @internal Constructed only by the generation-owned IM Runtime. */
     constructor(conversation: ConversationRef, content: string, generation: number, reply: (content: SendContent, requester?: PluginId, targetConversation?: ConversationAddress) => Promise<DeliveryReceipt>, sender?: MessageSenderRef | undefined, metadata?: Readonly<Record<string, unknown>>, 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
@@ -126,10 +133,15 @@ export declare class Message {
     /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
     message?: MessageRef | undefined, endpointId?: string | undefined, mentioned?: boolean | undefined, replyTo?: {
         readonly id: string;
-    } | undefined);
+    } | undefined, client?: () => unknown, clientAdapter?: string | undefined);
     /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
     get id(): string | undefined;
     readonly $reply: (content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * Platform-native Client that received this message. The getter is
+     * generation-scoped; retaining the returned Client after dispatch is invalid.
+     */
+    get $client(): unknown;
     readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<DeliveryReceipt>;
     /**
      * 向同 Endpoint 的另一个通道发送消息（通用）。
@@ -176,4 +188,4 @@ export declare class Message {
      */
     readonly $replyToChannel: (channelId: string, guildId: string, content: SendContent, threadId?: string) => Promise<DeliveryReceipt>;
 }
-export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;
+export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | '$client' | 'replace'>, initialPayload: unknown, resolveClient?: () => unknown): OutboundEnvelope;

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

@@ -43,6 +43,9 @@ export class Message {
     endpointId;
     mentioned;
     replyTo;
+    clientAdapter;
+    #resolveClient;
+    /** @internal Constructed only by the generation-owned IM Runtime. */
     constructor(conversation, content, generation, reply, sender, metadata = Object.freeze({}), 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
@@ -50,7 +53,9 @@ export class Message {
      */
     segments, 
     /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
-    message, endpointId, mentioned, replyTo) {
+    message, endpointId, mentioned, replyTo, client = () => {
+        throw new Error('Message has no Endpoint Client context');
+    }, clientAdapter) {
         this.conversation = conversation;
         this.content = content;
         this.generation = generation;
@@ -61,6 +66,8 @@ export class Message {
         this.endpointId = endpointId;
         this.mentioned = mentioned;
         this.replyTo = replyTo;
+        this.clientAdapter = clientAdapter;
+        this.#resolveClient = client;
         this.$reply = (content) => reply(content);
         this.$replyFrom = (requester, content) => reply(content, requester);
         this.$sendTo = (target, content) => reply(content, undefined, target);
@@ -101,6 +108,13 @@ export class Message {
         return this.message?.id;
     }
     $reply;
+    /**
+     * Platform-native Client that received this message. The getter is
+     * generation-scoped; retaining the returned Client after dispatch is invalid.
+     */
+    get $client() {
+        return this.#resolveClient();
+    }
     $replyFrom;
     /**
      * 向同 Endpoint 的另一个通道发送消息（通用）。
@@ -144,11 +158,12 @@ export class Message {
      */
     $replyToChannel;
 }
-export function createOutboundEnvelope(request, initialPayload) {
+export function createOutboundEnvelope(request, initialPayload, resolveClient = () => undefined) {
     let payload = initialPayload;
     return Object.freeze({
         ...request,
         get payload() { return payload; },
+        get $client() { return resolveClient(); },
         replace(next) { payload = next; },
     });
 }

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

@@ -1,19 +1,19 @@
 import { Scope, generationAdmissionBinder, type GenerationAdmissionGate, type PluginId, type RuntimeSnapshot, type SnapshotLease, type SnapshotReader } from '@zhin.js/plugin-runtime';
 import { MessageBus } from './message-bus.js';
-import { type AdapterOperation, type EndpointManagement, type EndpointManagementCapability, type AdapterEndpointPhase, type EndpointContentResolveContext } from '@zhin.js/adapter';
-import { type ConversationEventStore, type ConversationContextBlock, type ConversationReference, type ConversationResolution, type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
-import { Message, type ConversationAddress, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type MessageSenderRef, type SendRequest } from './contracts.js';
+import { type AdapterOperation, type EndpointManagement, type EndpointManagementCapability, type AdapterEndpointPhase, type EndpointContentResolveContext, type EndpointEvent, type EndpointEventGateway } from '@zhin.js/adapter';
+import { type ConversationEventStore, type ConversationContextBlock, type ConversationReference, type ConversationResolution, type ConversationRef, type DeliveryReceipt, type EndpointCapabilities, type MessageRef } from '@zhin.js/im-contract';
+import { Message, type ConversationAddress, type IncomingMessage, type OutboundMessageService, type MessageSenderRef, type SendRequest } from './contracts.js';
 import { LoginAssist } from '../../built/login-assist.js';
-import type { Notice } from '../../notice.js';
-import type { Request } from '../../request.js';
-import type { SystemEvent } from '../../system-event.js';
 import type { UserInteraction } from '@zhin.js/interaction';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { type RuntimeInteractiveHandler } from './interactive.js';
-export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
+/** @public Stable inbound and outbound IM gateway token for Adapter integrations. */
+export declare const outboundMessageToken: import("@zhin.js/plugin-runtime").Token<OutboundMessageService>;
 /** Generation-owned ingress hooks before ordinary dispatch and after it misses. */
 export interface IngressRoute {
     preRoute?(message: Message, lease: SnapshotLease, requester: PluginId, conversationSequence: number | undefined): Promise<boolean>;
+    /** A live pre-route handoff that must run before handlers and commands. */
+    shouldRouteBeforeDispatch?(message: Message): boolean;
     route(message: Message, lease: SnapshotLease, requester: PluginId, conversationSequence: number | undefined): Promise<boolean>;
 }
 export declare const ingressRouteToken: import("@zhin.js/plugin-runtime").Token<IngressRoute>;
@@ -49,12 +49,14 @@ export interface ImRuntimeOptions {
      */
     readonly enrichSender?: (sender: MessageSenderRef | undefined, conversation: IncomingMessage['conversation'], snapshot: RuntimeSnapshot) => MessageSenderRef | undefined;
 }
-export declare class ImRuntime implements MessageGateway {
+export declare class ImRuntime implements OutboundMessageService {
     #private;
     conversationEvents: ConversationEventStore;
     constructor(options?: ImRuntimeOptions);
     /** Process composition replaces the bootstrap memory store after required DB activation. */
     replaceConversationEventStore(store: ConversationEventStore): void;
+    /** Pins all nested IM operations to the snapshot current at operation ingress. */
+    runWithSnapshotView<T>(operation: () => Promise<T>): Promise<T>;
     resolveConversationReference(lease: SnapshotLease, reference: ConversationReference, context: EndpointContentResolveContext): Promise<ConversationResolution>;
     readConversationContext(conversation: ConversationRef, consumer: string, throughSequence: number, limit?: number, excludeMessageId?: string): Promise<Readonly<{
         blocks: readonly ConversationContextBlock[];
@@ -66,7 +68,11 @@ export declare class ImRuntime implements MessageGateway {
     readonly messageBus: MessageBus;
     readonly loginAssist: LoginAssist;
     install(resources: Scope): void;
-    [generationAdmissionBinder](gate: GenerationAdmissionGate): MessageGateway;
+    /** The sole Adapter ingress, also installed as endpointEventGatewayToken. */
+    readonly endpointEvents: EndpointEventGateway & {
+        [generationAdmissionBinder](gate: GenerationAdmissionGate): EndpointEventGateway;
+    };
+    [generationAdmissionBinder](gate: GenerationAdmissionGate): OutboundMessageService;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
      * 在 Command dispatch 之前路由：action 段 / 数字回跳 / 指令预填 payload。
@@ -84,11 +90,10 @@ export declare class ImRuntime implements MessageGateway {
      * 返回注销函数。listener 抛错不会阻断消息链路。
      */
     onMessage(listener: (event: RuntimeMessageEvent) => void): () => void;
-    receive(input: IncomingMessage): Promise<MessageDispatchResult>;
     send(request: SendRequest): Promise<DeliveryReceipt>;
-    receiveNotice(notice: Notice): Promise<void>;
-    receiveRequest(request: Request): Promise<void>;
-    receiveSystem(event: SystemEvent): Promise<void>;
+    /** Sends through the exact generation lease that admitted the current operation. */
+    sendWithSnapshotLease(lease: SnapshotLease, request: SendRequest): Promise<DeliveryReceipt>;
+    receiveEndpointEvent(event: EndpointEvent, admission?: GenerationAdmissionGate): Promise<unknown>;
     /** Console `endpoint.list` — empty until Adapter Feature projection is ready. */
     listEndpoints(): readonly {
         readonly id: string;
@@ -101,6 +106,11 @@ export declare class ImRuntime implements MessageGateway {
         readonly operations: readonly AdapterOperation[];
         readonly managementCapabilities: readonly EndpointManagementCapability[];
     }[];
+    /** Exact operation capabilities for one concrete live Endpoint. */
+    endpointCapabilities(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+    }): EndpointCapabilities | undefined;
     /**
      * Console `GET /api/stats` 同源计数：非 root 插件节点 + AdapterIndex endpoints。
      * 供命令 / 状态卡等在 Plugin Runtime 下读取（legacy `root.adapters` / `root.children` 已不存在）。

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

@@ -1,14 +1,14 @@
 import { createToken, generationAdmissionBinder, htmlRendererToken, } from '@zhin.js/plugin-runtime';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createPermissionHost, permissionHostToken } from '@zhin.js/permission';
 import { MessageBus, messageBusToken } from './message-bus.js';
-import { adapterFeatureId, isAdapterIndex, resolveEndpointManagement, } from '@zhin.js/adapter';
+import { adapterFeatureId, isAdapterIndex, resolveEndpointManagement, endpointEventGatewayToken, } from '@zhin.js/adapter';
 import { MemoryConversationEventStore, conversationRefKey, messageRefKey, } from '@zhin.js/im-contract';
 import { segmentsToPlainText } from '../../built/segment-contract/text.js';
 import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
 import { isHandlerIndex, handlerFeatureId } from '../../feature/handler.js';
 import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
 import { Message, createOutboundEnvelope, } from './contracts.js';
-import { sideEventGatewayToken, } from './side-event-gateway.js';
 import { loginAssistToken } from './login-assist-host.js';
 import { LoginAssist } from '../../built/login-assist.js';
 import { sideEventSendChannel } from '../../side-event/base.js';
@@ -20,7 +20,8 @@ import { keyboardFallbackStore } from '../../built/interactive-segments/fallback
 import { assertUserInteractionRequest, parseUserInteractionAnswer, projectUserInteraction, renderUserInteraction, } from '../../built/user-interaction.js';
 import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveConversationKey, } from './interactive.js';
 const logger = getLogger('im');
-export const messageGatewayToken = createToken('zhin.im.message-gateway');
+/** @public Stable inbound and outbound IM gateway token for Adapter integrations. */
+export const outboundMessageToken = createToken('zhin.im.outbound-message');
 export const ingressRouteToken = createToken('zhin.im.ingress-route');
 export const messagePreviewLimit = 200;
 class UserInteractionTimeoutError extends Error {
@@ -47,6 +48,7 @@ export class ImRuntime {
     #messageListeners = new Set();
     #interactiveHandlers = [];
     #interactionClaims = new Map();
+    #operationSnapshot = new AsyncLocalStorage();
     #snapshots;
     #inboundClaim;
     #enrichSender;
@@ -64,6 +66,21 @@ export class ImRuntime {
     replaceConversationEventStore(store) {
         this.conversationEvents = store;
     }
+    /** Pins all nested IM operations to the snapshot current at operation ingress. */
+    async runWithSnapshotView(operation) {
+        const inherited = this.#operationSnapshot.getStore();
+        if (inherited?.active)
+            return operation();
+        if (!this.#snapshots)
+            throw new Error('ImRuntime is not attached to a Root');
+        const lease = this.#snapshots.acquire();
+        try {
+            return await this.#operationSnapshot.run(lease, operation);
+        }
+        finally {
+            lease.release();
+        }
+    }
     async resolveConversationReference(lease, reference, context) {
         if (!this.#snapshots?.owns(lease) || !lease.active) {
             return Object.freeze({ status: 'expired', code: 'generation_lease_expired' });
@@ -102,29 +119,20 @@ export class ImRuntime {
     messageBus = new MessageBus();
     loginAssist = new LoginAssist();
     install(resources) {
-        resources.provide(messageGatewayToken, this);
-        resources.provide(sideEventGatewayToken, this.#sideEventGateway);
+        resources.provide(outboundMessageToken, this);
+        resources.provide(endpointEventGatewayToken, this.endpointEvents);
         resources.provide(loginAssistToken, this.loginAssist);
         resources.provide(permissionHostToken, this.permissionHost);
         resources.provide(messageBusToken, this.messageBus);
     }
-    #sideEventGateway = (() => {
+    /** The sole Adapter ingress, also installed as endpointEventGatewayToken. */
+    endpointEvents = (() => {
         const self = this;
         const gateway = {
-            receiveNotice: (notice) => self.receiveNotice(notice),
-            receiveRequest: (request) => self.receiveRequest(request),
-            receiveSystem: (event) => self.receiveSystem(event),
+            receive: (event) => self.receiveEndpointEvent(event),
             [generationAdmissionBinder](gate) {
                 return Object.freeze({
-                    receiveNotice: async (notice) => {
-                        await gate.enter(() => self.receiveNotice(notice));
-                    },
-                    receiveRequest: async (request) => {
-                        await gate.enter(() => self.receiveRequest(request));
-                    },
-                    receiveSystem: async (event) => {
-                        await gate.enter(() => self.receiveSystem(event));
-                    },
+                    receive: async (event) => gate.enter(() => self.receiveEndpointEvent(event, gate)),
                 });
             },
         };
@@ -132,8 +140,6 @@ export class ImRuntime {
     })();
     [generationAdmissionBinder](gate) {
         const gateway = {
-            receive: async (input) => gate.enter(() => this.#receive(input, gate))
-                ?? Object.freeze({ matched: false }),
             send: async (request) => gate.enter(() => this.send(request))
                 ?? failedReceipt('generation_not_admitted'),
             registerInteractiveHandler: (prefix, handler) => this.#registerInteractiveHandler(prefix, handler, gate),
@@ -315,10 +321,8 @@ export class ImRuntime {
             }
         }
     }
-    async receive(input) {
-        return this.#receive(input);
-    }
-    async #receive(input, admission) {
+    async #receive(source, admission) {
+        const input = source.payload;
         const lease = this.#acquire();
         let active = true;
         try {
@@ -354,7 +358,11 @@ export class ImRuntime {
                         mentioned: input.mentioned,
                     },
                 }, lease.value);
-            }, enrichedSender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.message, input.endpointId, input.mentioned, input.replyTo);
+            }, enrichedSender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.message, input.endpointId, input.mentioned, input.replyTo, () => {
+                if (!active)
+                    throw new Error('Message Client scope has ended');
+                return source.client;
+            }, source.endpoint.adapter);
             let conversationSequence;
             if (input.message?.id) {
                 const appended = await this.conversationEvents.append(Object.freeze({
@@ -394,7 +402,16 @@ export class ImRuntime {
                         result = Object.freeze({ matched: true, command: 'pre-route', owner: requester });
                         return;
                     }
-                    await this.#runHandlers(lease.value, 'message.receive', [message]);
+                    if (ingressRoute?.shouldRouteBeforeDispatch?.(message) === true) {
+                        const handled = await ingressRoute.route(message, lease, requester, conversationSequence);
+                        if (handled) {
+                            result = Object.freeze({ matched: true, command: 'ai', owner: requester });
+                            return;
+                        }
+                    }
+                    await this.#runHandlers(lease.value, 'message.receive', [
+                        withEndpointEventPayload(source, message),
+                    ]);
                     result = await this.#dispatchInteractive(message, requester, admission)
                         ?? await this.#dispatcher.dispatch(message, lease.value, interactionFactory);
                     if (!result.matched && ingressRoute) {
@@ -425,7 +442,7 @@ export class ImRuntime {
         }
         finally {
             active = false;
-            lease.release();
+            this.#release(lease);
         }
     }
     async send(request) {
@@ -434,18 +451,26 @@ export class ImRuntime {
             return await this.#sendWithSnapshot(request, lease.value);
         }
         finally {
-            lease.release();
+            this.#release(lease);
         }
     }
-    async receiveNotice(notice) {
+    /** Sends through the exact generation lease that admitted the current operation. */
+    async sendWithSnapshotLease(lease, request) {
+        if (!this.#snapshots?.owns(lease) || !lease.active) {
+            throw new Error('Outbound message generation lease expired');
+        }
+        return this.#sendWithSnapshot(request, lease.value);
+    }
+    async #receiveNotice(source) {
+        const notice = source.payload;
         const event = conversationEventFromNotice(notice);
         if (event)
             await this.conversationEvents.append(event);
-        await this.#receiveSideEvent('notice.receive', notice);
+        await this.#receiveSideEvent(withEndpointEventPayload(source, notice));
     }
-    async receiveRequest(request) {
-        await this.#withRequestActionScope(request, async (scoped) => {
-            await this.#receiveSideEvent('request.receive', scoped);
+    async #receiveRequest(source) {
+        await this.#withRequestActionScope(source.payload, async (scoped) => {
+            await this.#receiveSideEvent(withEndpointEventPayload(source, scoped));
         });
     }
     async #withRequestActionScope(request, dispatch) {
@@ -471,16 +496,38 @@ export class ImRuntime {
             await Promise.allSettled([...actions]);
         }
     }
-    async receiveSystem(event) {
-        await this.#receiveSideEvent('system.receive', event);
+    async #receiveSystem(source) {
+        await this.#receiveSideEvent(source);
     }
-    async #receiveSideEvent(event, payload) {
+    async #receiveSideEvent(event) {
         const lease = this.#acquire();
         try {
-            await this.#runHandlers(lease.value, event, [payload]);
+            await this.#runHandlers(lease.value, event.name, [event]);
         }
         finally {
-            lease.release();
+            this.#release(lease);
+        }
+    }
+    async receiveEndpointEvent(event, admission) {
+        switch (event.name) {
+            case 'message.receive':
+                return this.#receive(event, admission);
+            case 'notice.receive':
+                return this.#receiveNotice(event);
+            case 'request.receive':
+                return this.#receiveRequest(event);
+            case 'system.receive':
+                return this.#receiveSystem(event);
+            default: {
+                const lease = this.#acquire();
+                try {
+                    await this.#runHandlers(lease.value, event.name, [event]);
+                    return undefined;
+                }
+                finally {
+                    this.#release(lease);
+                }
+            }
         }
     }
     /**
@@ -518,7 +565,8 @@ export class ImRuntime {
             return;
         const options = {
             resolveInteraction: (name, interactionArgs) => {
-                const payload = interactionArgs[0];
+                const context = interactionArgs[0];
+                const payload = context?.payload;
                 if (name === 'message.receive' && payload instanceof Message) {
                     return this.createInteraction(payload);
                 }
@@ -551,13 +599,30 @@ export class ImRuntime {
                 }));
             }
             finally {
-                lease.release();
+                this.#release(lease);
             }
         }
         catch {
             return Object.freeze([]);
         }
     }
+    /** Exact operation capabilities for one concrete live Endpoint. */
+    endpointCapabilities(input) {
+        try {
+            const lease = this.#acquire();
+            try {
+                const index = requireAdapters(lease.value);
+                const id = index.resolve(input.adapter, input.endpointKey);
+                return id ? index.capabilities(id) : undefined;
+            }
+            finally {
+                this.#release(lease);
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Console `GET /api/stats` 同源计数：非 root 插件节点 + AdapterIndex endpoints。
      * 供命令 / 状态卡等在 Plugin Runtime 下读取（legacy `root.adapters` / `root.children` 已不存在）。
@@ -578,7 +643,7 @@ export class ImRuntime {
                 });
             }
             finally {
-                lease.release();
+                this.#release(lease);
             }
         }
         catch {
@@ -612,7 +677,7 @@ export class ImRuntime {
                 });
             }
             finally {
-                lease.release();
+                this.#release(lease);
             }
         }
         catch {
@@ -640,7 +705,7 @@ export class ImRuntime {
             return { messageId: result.message?.id ?? '' };
         }
         finally {
-            lease.release();
+            this.#release(lease);
         }
     }
     /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
@@ -678,7 +743,7 @@ export class ImRuntime {
             return control ? await run(control) : fallback;
         }
         finally {
-            lease.release();
+            this.#release(lease);
         }
     }
     /** Run one management operation while the Endpoint generation stays leased. */
@@ -691,13 +756,13 @@ export class ImRuntime {
             return null;
         }
         try {
-            const endpoint = requireAdapters(lease.value).instance(adapter, endpointKey);
+            const endpoint = requireAdapters(lease.value).connection(adapter, endpointKey);
             if (!endpoint)
                 return null;
             return await run(resolveEndpointManagement(endpoint) ?? Object.freeze({}));
         }
         finally {
-            lease.release();
+            this.#release(lease);
         }
     }
     async #sendWithSnapshot(request, snapshot) {
@@ -710,11 +775,19 @@ export class ImRuntime {
         catch {
             return rejectedReceipt('outbound_payload_rejected');
         }
+        let adapters;
+        try {
+            adapters = requireAdapters(snapshot);
+        }
+        catch (error) {
+            return receiptFromEndpointError(error);
+        }
         const envelope = createOutboundEnvelope({
             conversation: request.conversation,
             requester: request.requester,
             generation: snapshot.generation,
-        }, initialPayload);
+            clientAdapter: adapters.clientAdapter(adapter),
+        }, initialPayload, () => adapters.clientById(adapter));
         let terminalEntered = false;
         let receipt;
         try {
@@ -787,10 +860,18 @@ export class ImRuntime {
         return receipt ?? failedReceipt('outbound_delivery_incomplete');
     }
     #acquire() {
+        const inherited = this.#operationSnapshot.getStore();
+        if (inherited?.active)
+            return inherited;
         if (!this.#snapshots)
             throw new Error('ImRuntime is not attached to a Root');
         return this.#snapshots.acquire();
     }
+    #release(lease) {
+        if (this.#operationSnapshot.getStore() === lease)
+            return;
+        lease.release();
+    }
     /**
      * interactive 回跳分发（Command dispatch 之前）：action 段 / 中央 fallback
      * 数字回跳 / 指令预填 payload → prefix 最长匹配 handler。
@@ -1113,3 +1194,11 @@ function abortError(signal, fallback) {
         return signal.reason;
     return new Error(fallback);
 }
+function withEndpointEventPayload(source, payload) {
+    return Object.freeze({
+        name: source.name,
+        payload,
+        endpoint: source.endpoint,
+        client: source.client,
+    });
+}

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

@@ -7,4 +7,3 @@ export * from './message-dispatcher.js';
 export * from './outbound-renderer.js';
 export * from './outbound-segments.js';
 export * from './service-tokens.js';
-export * from './side-event-gateway.js';

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

@@ -7,4 +7,3 @@ export * from './message-dispatcher.js';
 export * from './outbound-renderer.js';
 export * from './outbound-segments.js';
 export * from './service-tokens.js';
-export * from './side-event-gateway.js';

package/lib/plugin-runtime/im/login-assist-host.d.ts

@@ -1,6 +1,6 @@
 import { LoginAssist } from '../../built/login-assist.js';
 /**
- * Plugin Runtime login-assist port（与 messageGatewayToken / sideEventGatewayToken 并列）。
+ * Plugin Runtime login-assist port（与出站消息服务并列）。
  * 适配器 waitForInput；Console / stdin 经 listPending + submit 消费。
  */
 export declare const loginAssistToken: import("@zhin.js/plugin-runtime").Token<LoginAssist>;

package/lib/plugin-runtime/im/login-assist-host.js

@@ -1,6 +1,6 @@
 import { createToken } from '@zhin.js/plugin-runtime';
 /**
- * Plugin Runtime login-assist port（与 messageGatewayToken / sideEventGatewayToken 并列）。
+ * Plugin Runtime login-assist port（与出站消息服务并列）。
  * 适配器 waitForInput；Console / stdin 经 listPending + submit 消费。
  */
 export const loginAssistToken = createToken('zhin.im.login-assist');

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

@@ -0,0 +1,6 @@
+/**
+ * Public IM gateway contract exposed from `zhin.js/core/runtime`.
+ * @module zhin.js/core/runtime
+ */
+export { outboundMessageToken } from './im-runtime.js';
+export { Message, type ComponentCall, type ConversationAddress, type IncomingContext, type IncomingMessage, type MessageDispatchResult, type OutboundMessageService, type MessageSenderRef, type OutboundEnvelope, type RawContent, type SendContent, type SendRequest, } from './contracts.js';

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

@@ -0,0 +1,6 @@
+/**
+ * Public IM gateway contract exposed from `zhin.js/core/runtime`.
+ * @module zhin.js/core/runtime
+ */
+export { outboundMessageToken } from './im-runtime.js';
+export { Message, } from './contracts.js';

package/lib/side-event/dispatch.d.ts

@@ -1,4 +1,4 @@
-import type { SideEventGateway } from '../plugin-runtime/im/side-event-gateway.js';
+import type { EndpointEventEmitter } from '@zhin.js/adapter';
 import { type OneBotLikeRawEvent, type SideEventPlatform } from './normalize.js';
 export interface OneBotLikeSideEventInput {
     readonly adapter: string;
@@ -9,7 +9,7 @@ export interface OneBotLikeSideEventInput {
     readonly reject?: (flag: string, reason?: string) => void | Promise<void>;
 }
 /**
- * Normalize OneBot / icqq-style notice|request|meta payloads and forward to SideEventGateway.
+ * Normalize OneBot / icqq-style notice|request|meta payloads and feed Endpoint.emit().
  * Returns which kind was dispatched, or null when the payload is not a side event.
  */
-export declare function receiveOneBotLikeSideEvent(gateway: SideEventGateway, input: OneBotLikeSideEventInput): Promise<'notice' | 'request' | 'system' | null>;
+export declare function receiveOneBotLikeSideEvent(emit: EndpointEventEmitter, input: OneBotLikeSideEventInput): Promise<'notice' | 'request' | 'system' | null>;

package/lib/side-event/dispatch.js

@@ -1,9 +1,9 @@
 import { buildNotice, buildRequest, buildSystem, mapNoticeParts, mapRequestParts, resolveSideEventDedupeKey, senderFromId, } from './normalize.js';
 /**
- * Normalize OneBot / icqq-style notice|request|meta payloads and forward to SideEventGateway.
+ * Normalize OneBot / icqq-style notice|request|meta payloads and feed Endpoint.emit().
  * Returns which kind was dispatched, or null when the payload is not a side event.
  */
-export async function receiveOneBotLikeSideEvent(gateway, input) {
+export async function receiveOneBotLikeSideEvent(emit, input) {
     const raw = input.raw;
     const platform = input.platform ?? 'onebot';
     const postType = String(raw.post_type ?? raw.type ?? '');
@@ -47,7 +47,7 @@ export async function receiveOneBotLikeSideEvent(gateway, input) {
                 ? { $role: 'admin', $enabled: String(raw.sub_type ?? '') === 'set' }
                 : {}),
         });
-        await gateway.receiveNotice(notice);
+        await emit('notice.receive', notice);
         return 'notice';
     }
     if (postType === 'request' || postType.startsWith('request.')) {
@@ -96,7 +96,7 @@ export async function receiveOneBotLikeSideEvent(gateway, input) {
             },
         });
         try {
-            await gateway.receiveRequest(request);
+            await emit('request.receive', request);
         }
         finally {
             active = false;
@@ -127,7 +127,7 @@ export async function receiveOneBotLikeSideEvent(gateway, input) {
             $sub_type: subType ?? metaType,
             $timestamp: toMillis(raw.time),
         });
-        await gateway.receiveSystem(system);
+        await emit('system.receive', system);
         return 'system';
     }
     return null;

package/lib/utils.d.ts

@@ -70,7 +70,7 @@ export declare namespace segment {
         backgroundColor?: string;
         fileName?: string;
     }): HtmlSegment;
-    /** @alias htmlCard */
+    /** Short alias for {@link htmlCard}. */
     const html: typeof htmlCard;
     /** 出站 Markdown 段（Adapter policy 决定 image/text/origin） */
     function markdown(content: string, options?: Omit<MarkdownSegment['data'], 'content'>): MarkdownSegment;

package/lib/utils.js

@@ -98,7 +98,7 @@ export function segment(type, data) {
         return new HtmlSegment(options);
     }
     segment.htmlCard = htmlCard;
-    /** @alias htmlCard */
+    /** Short alias for {@link htmlCard}. */
     segment.html = htmlCard;
     /** 出站 Markdown 段（Adapter policy 决定 image/text/origin） */
     function markdown(content, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.5.13",
+  "version": "1.5.15",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -75,18 +75,18 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/component": "1.0.12",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/database": "1.0.79",
-    "@zhin.js/handler": "1.0.3",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/component": "1.0.13",
+    "@zhin.js/handler": "1.0.4",
+    "@zhin.js/database": "1.0.81",
     "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/interaction": "1.0.1",
-    "@zhin.js/kernel": "1.0.7",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/middleware": "1.0.12",
-    "@zhin.js/plugin-runtime": "1.1.7",
-    "@zhin.js/permission": "1.0.3",
+    "@zhin.js/kernel": "1.0.8",
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/middleware": "1.0.13",
+    "@zhin.js/permission": "1.0.4",
+    "@zhin.js/plugin-runtime": "1.1.8",
     "@zhin.js/schema": "1.0.73"
   },
   "peerDependencies": {
@@ -102,7 +102,7 @@
     "@types/qrcode": "^1.5.6",
     "ajv": "8.18.0",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.5.6"
+    "@zhin.js/ai": "1.5.7"
   },
   "repository": {
     "type": "git",

package/lib/agent-prompt.d.ts

@@ -1,39 +0,0 @@
-/**
- * Agent system-prompt extension contract (per IM platform / adapter).
- *
- * Implementations live in adapter plugins; resolution runs in @zhin.js/agent.
- */
-export type AgentPromptSlot = 'orchestrator' | 'deferred_worker';
-/** Minimal tool shape for deferred catalog selection (no @zhin.js/ai import). */
-export interface DeferredToolCatalogItem {
-    name: string;
-    description: string;
-}
-export interface AgentPromptBuildContext {
-    slot: AgentPromptSlot;
-    /** Authenticated IM platform projected by the ingress adapter. */
-    platform: string;
-    /** Truncated user message for intent hints (~500 chars). */
-    userMessagePreview?: string;
-    deferred?: {
-        goal: string;
-        toolQuery?: string;
-        domainStats?: string;
-    };
-}
-export interface AgentPromptSection {
-    /** Stable id for debug / logs (e.g. platform.icqq.orchestrator). */
-    id: string;
-    title?: string;
-    body: string;
-    /** Lower sorts earlier; default 100. */
-    priority?: number;
-}
-export interface AgentPromptContributor {
-    readonly platform: string;
-    buildSections(ctx: AgentPromptBuildContext): Promise<AgentPromptSection[] | null>;
-    /** When true, platform may supply selectDeferredTools for this task. */
-    matchesDeferredTask?(ctx: AgentPromptBuildContext): boolean;
-    /** Non-null replaces default TF-IDF deferred tool selection. */
-    selectDeferredTools?(query: string, goal: string, catalog: DeferredToolCatalogItem[], maxTools: number): DeferredToolCatalogItem[] | null;
-}

package/lib/agent-prompt.js

@@ -1,6 +0,0 @@
-/**
- * Agent system-prompt extension contract (per IM platform / adapter).
- *
- * Implementations live in adapter plugins; resolution runs in @zhin.js/agent.
- */
-export {};

package/lib/plugin-runtime/im/side-event-gateway.d.ts

@@ -1,13 +0,0 @@
-import type { Notice } from '../../notice.js';
-import type { Request } from '../../request.js';
-import type { SystemEvent } from '../../system-event.js';
-/**
- * Plugin Runtime 侧事件入站口（与 messageGatewayToken 并列）。
- * 适配器归一 Notice / Request / SystemEvent 后调用，由 ImRuntime 分发给 HandlerIndex。
- */
-export interface SideEventGateway {
-    receiveNotice(notice: Notice): Promise<void>;
-    receiveRequest(request: Request): Promise<void>;
-    receiveSystem(event: SystemEvent): Promise<void>;
-}
-export declare const sideEventGatewayToken: import("@zhin.js/plugin-runtime").Token<SideEventGateway>;

package/lib/plugin-runtime/im/side-event-gateway.js

@@ -1,2 +0,0 @@
-import { createToken } from '@zhin.js/plugin-runtime';
-export const sideEventGatewayToken = createToken('zhin.im.side-event-gateway');