@zhin.js/core 1.5.7 → 1.5.9

package/lib/adapter.d.ts

@@ -88,8 +88,7 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
     sendMessage(options: SendOptions): Promise<string>;
     /**
      * `call.recallMessage` 事件链（prompt.ts 超时撤回等）的统一出口：
-     * 经 canonical `EndpointControl` 端口撤回，classic 端点的 `$` 方法由
-     * `resolveEndpointControl` 迁移桥适配。
+     * 经 canonical `EndpointControl` 端口撤回。
      */
     private recallEndpointMessage;
     /**

package/lib/adapter.js

@@ -1,5 +1,5 @@
 import { assertOutbound, DEFAULT_ENDPOINT_CAPABILITIES, hasInbound, } from "./endpoint-capabilities.js";
-import { resolveEndpointControl } from "@zhin.js/adapter";
+import { endpointControlOf } from "@zhin.js/adapter";
 import { connectEndpointInstance, disconnectEndpointInstance } from "./built/connect-endpoint-instance.js";
 import { EventEmitter } from "node:events";
 import { getOutboundReplyStore } from "./built/dispatcher.js";
@@ -123,10 +123,17 @@ export class Adapter extends EventEmitter {
             return false;
         }
         this.#pendingMessages++;
-        await this.inboundPipeline.receive(message, () => {
-            EventEmitter.prototype.emit.call(this, 'message.receive', message);
-        });
-        return true;
+        try {
+            await this.inboundPipeline.receive(message, () => {
+                EventEmitter.prototype.emit.call(this, 'message.receive', message);
+            });
+            return true;
+        }
+        finally {
+            // Inbound pipeline errors must not leak the concurrency budget; the
+            // non-await path uses InboundMessagePipeline.decrementPending in finally.
+            this.#pendingMessages = Math.max(0, this.#pendingMessages - 1);
+        }
     }
     /**
      * 出站富媒体能力（Publisher 按此过滤/降级；各 adapter 可覆盖）。
@@ -218,20 +225,26 @@ export class Adapter extends EventEmitter {
     }
     /**
      * `call.recallMessage` 事件链（prompt.ts 超时撤回等）的统一出口：
-     * 经 canonical `EndpointControl` 端口撤回，classic 端点的 `$` 方法由
-     * `resolveEndpointControl` 迁移桥适配。
+     * 经 canonical `EndpointControl` 端口撤回。
      */
     async recallEndpointMessage(endpointKey, messageId) {
         const endpoint = this.endpoints.get(endpointKey);
         if (!endpoint)
             throw new Error(`Endpoint ${endpointKey} not found`);
         assertOutbound(endpoint);
-        const control = resolveEndpointControl(endpoint);
+        const control = endpointControlOf(endpoint);
         if (!control?.recall) {
             throw new Error(`Endpoint ${endpointKey} does not support recall`);
         }
         this.logger.debug(formatCompact({ op: 'recall_message', msgId: messageId, endpoint: endpointKey }));
-        await control.recall(messageId);
+        await control.recall({
+            conversation: {
+                endpoint: { id: endpointKey, adapter: String(this.name) },
+                kind: 'private',
+                id: endpointKey,
+            },
+            id: messageId,
+        });
     }
     /**
      * 编辑已发送的消息。
@@ -244,7 +257,7 @@ export class Adapter extends EventEmitter {
         if (!endpoint)
             throw new Error(`Endpoint ${options.endpoint} not found`);
         assertOutbound(endpoint);
-        const control = resolveEndpointControl(endpoint);
+        const control = endpointControlOf(endpoint);
         if (control?.edit) {
             const rendered = await this.renderSendMessage({
                 context: options.context,
@@ -253,7 +266,14 @@ export class Adapter extends EventEmitter {
                 type: options.type,
                 content: options.content,
             });
-            await control.edit(options.messageId, rendered.content);
+            await control.edit({
+                conversation: {
+                    endpoint: { id: options.endpoint, adapter: String(this.name) },
+                    kind: options.type === 'group' ? 'group' : 'private',
+                    id: options.id,
+                },
+                id: options.messageId,
+            }, rendered.content);
             this.logger.debug(formatCompact({
                 edit: `${options.type}(${options.id})`,
                 endpoint: options.endpoint,

package/lib/built/adapter-process.d.ts

@@ -31,6 +31,11 @@ export declare class ProcessEndpoint implements Endpoint<{
         content: string;
         ts: number;
     }>;
+    get control(): {
+        recall: (message: {
+            id: string;
+        }) => Promise<void>;
+    };
     $recallMessage(id: string): Promise<void>;
     $sendMessage(options: SendOptions): Promise<string>;
     $connect(): Promise<void>;

package/lib/built/adapter-process.js

@@ -62,6 +62,11 @@ export class ProcessEndpoint {
         };
         return Message.from(event, base);
     }
+    get control() {
+        return {
+            recall: async (message) => this.$recallMessage(message.id),
+        };
+    }
     async $recallMessage(id) {
     }
     async $sendMessage(options) {

package/lib/built/ai-outbound/parse.d.ts

@@ -5,7 +5,7 @@ export declare function parseOutboundSegment(raw: unknown): Segment | null;
 /** 去掉嵌入 JSON 候选末尾的 markdown 围栏（模型常见 ```json … ``` 误输出）。 */
 export declare function trimTrailingMarkdownFence(raw: string): string;
 export declare function unwrapAiOutboundJsonCandidate(raw: string): string;
-/** 从「正文 + 嵌入 JSON」混合文本中提取 AI outbound JSON（协作群常见误输出）。 */
+/** Extract an embedded AI outbound JSON object from mixed prose. */
 export declare function extractEmbeddedAiOutboundJson(plain: string): {
     prose: string;
     jsonRaw: string;

package/lib/built/ai-outbound/parse.js

@@ -31,7 +31,7 @@ export function unwrapAiOutboundJsonCandidate(raw) {
     }
     return trimTrailingMarkdownFence(trimmed);
 }
-/** 从「正文 + 嵌入 JSON」混合文本中提取 AI outbound JSON（协作群常见误输出）。 */
+/** Extract an embedded AI outbound JSON object from mixed prose. */
 export function extractEmbeddedAiOutboundJson(plain) {
     const trimmed = plain.trim();
     if (!trimmed.includes('{'))

package/lib/built/ai-outbound/prompt.d.ts

@@ -7,5 +7,5 @@ export declare function buildAiOutboundPromptHint(input: {
     rosterLines?: string[];
     forceJsonOnly?: boolean;
 }): string;
-/** 检测入站是否含 handoff / @ 意图（协作群 structured_only 信号）。 */
+/** Detect whether inbound text explicitly requests a structured handoff. */
 export declare function detectInboundHandoffIntent(content: string): boolean;

package/lib/built/ai-outbound/prompt.js

@@ -33,7 +33,7 @@ export function buildAiOutboundPromptHint(input) {
     }
     return lines.join('\n');
 }
-/** 检测入站是否含 handoff / @ 意图（协作群 structured_only 信号）。 */
+/** Detect whether inbound text explicitly requests a structured handoff. */
 export function detectInboundHandoffIntent(content) {
     const t = content.trim();
     if (!t)

package/lib/built/ai-outbound/structured-detect.js

@@ -1,7 +1,6 @@
 /** structured_only：满足任一即进入结构化出站模式。 */
 export function isStructuredOutboundRequired(input) {
-    return Boolean(input.collaborationCell
-        || input.toolRequiresStructured
+    return Boolean(input.toolRequiresStructured
         || input.inboundHandoffIntent
         || input.adapterHasExtensions);
 }

package/lib/built/ai-outbound/types.d.ts

@@ -48,9 +48,7 @@ export interface AiOutboundParseContext {
     extensions?: readonly AiOutboundExtensionDefinition[];
 }
 export interface StructuredOutboundDetectInput {
-    /** 协作 Cell 活跃且可能 @ peer */
-    collaborationCell?: boolean;
-    /** 工具链要求结构化出站（如 group_delegate message JSON） */
+    /** 工具链要求结构化出站。 */
     toolRequiresStructured?: boolean;
     /** 用户入站含 handoff / @ 意图 */
     inboundHandoffIntent?: boolean;

package/lib/built/ai-trigger.d.ts

@@ -39,11 +39,6 @@ export interface AITriggerConfig {
     trusted?: string[];
     /** 是否在 AI 入参前拉取 $quote_id 对应消息正文（默认 true） */
     resolveQuotedMessages?: boolean;
-    /**
-     * 协作单元内 peer Bot 入站策略（ADR 0023）。
-     * mention-only：仅被 @ 时触发；off：与普通人消息相同规则。
-     */
-    peerMode?: 'mention-only' | 'off';
 }
 /**
  * AI 触发检查结果

package/lib/built/ai-trigger.js

@@ -27,7 +27,6 @@ export const DEFAULT_AI_TRIGGER_CONFIG = {
     masters: [],
     trusted: [],
     resolveQuotedMessages: true,
-    peerMode: 'mention-only',
 };
 // ============================================================================
 // 工具函数

package/lib/endpoint.d.ts

@@ -1,17 +1,17 @@
 import type { Adapters, Adapter } from './adapter.js';
 import type { EndpointCapabilitiesConfig, FullEndpoint } from './endpoint-capabilities.js';
-import type { EndpointWithManagement } from '@zhin.js/adapter';
+import type { EndpointWithControl, EndpointWithManagement } from '@zhin.js/adapter';
 export type { EndpointChannel, EndpointChannelParent, EndpointFriend, EndpointGroup, EndpointManagement, EndpointWithManagement, EndpointManagementCapability, } from '@zhin.js/adapter';
 export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
 export type { EndpointControl, EndpointWithControl } from '@zhin.js/adapter';
-export { resolveEndpointControl } from '@zhin.js/adapter';
+export { endpointControlOf } from '@zhin.js/adapter';
 export type { EndpointCapability, EndpointCapabilitiesConfig, InboundEndpoint, OutboundEndpoint, FullEndpoint, CapableEndpoint, } from './endpoint-capabilities.js';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';
 /**
  * Endpoint 接口：全双工平台机器人（入站 + 出站）。
  * 纯入站 / 纯出站请实现 InboundEndpoint / OutboundEndpoint。
  */
-export type Endpoint<Config extends object = object, Event extends object = object> = FullEndpoint<Config, Event> & EndpointWithManagement;
+export type Endpoint<Config extends object = object, Event extends object = object> = FullEndpoint<Config, Event> & EndpointWithManagement & EndpointWithControl;
 export declare namespace Endpoint {
     type Config<K extends keyof Adapters = keyof Adapters> = Adapter.EndpointConfig<Adapter.InferEndpoint<Adapters[K]>> & EndpointCapabilitiesConfig & {
         context: K;

package/lib/endpoint.js

@@ -1,3 +1,3 @@
 export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
-export { resolveEndpointControl } from '@zhin.js/adapter';
+export { endpointControlOf } from '@zhin.js/adapter';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';

package/lib/feature/handler.d.ts

@@ -0,0 +1,10 @@
+/** Authoring API for Handler Feature — implementation in `@zhin.js/feature-kit`. */
+export { defineHandler, parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, type HandlerEventMap, type HandlerDefinition, type HandlerDescriptor, } from '@zhin.js/feature-kit';
+import type { Plugin } from '../plugin.js';
+type KnownKeys<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+declare module '@zhin.js/feature-kit' {
+    interface HandlerEventMap extends KnownKeys<Plugin.Lifecycle> {
+    }
+}

package/lib/feature/handler.js

@@ -0,0 +1,2 @@
+/** Authoring API for Handler Feature — implementation in `@zhin.js/feature-kit`. */
+export { defineHandler, parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, } from '@zhin.js/feature-kit';

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

@@ -1,8 +1,9 @@
-import { Scope, type PluginId, type RuntimeSnapshot, type SnapshotLease, type SnapshotStore } from '@zhin.js/plugin-runtime';
+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 EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
+import { type EndpointManagement, type EndpointManagementCapability, type AdapterEndpointPhase } 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 MessageSenderRef, type SendRequest } from './contracts.js';
+import type { CommandPrompt } from '@zhin.js/command';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { type RuntimeInteractiveHandler } from './interactive.js';
 export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
@@ -45,15 +46,23 @@ export interface ImRuntimeOptions {
 export declare class ImRuntime implements MessageGateway {
     #private;
     constructor(options?: ImRuntimeOptions);
-    attach(snapshots: SnapshotStore): void;
+    attach(snapshots: SnapshotReader): void;
     readonly permissionHost: import("@zhin.js/permission").PermissionHost;
     readonly messageBus: MessageBus;
     install(resources: Scope): void;
+    [generationAdmissionBinder](gate: GenerationAdmissionGate): MessageGateway;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
      * 在 Command dispatch 之前路由：action 段 / 数字回跳 / 指令预填 payload。
      */
     registerInteractiveHandler(prefix: string, handler: RuntimeInteractiveHandler): () => void;
+    /**
+     * Bound Prompt for this conversation.
+     * `bind.subjectId` waits for that user (e.g. master) instead of the message sender.
+     */
+    createPrompt(message: Message, bind?: {
+        readonly subjectId: string;
+    }): CommandPrompt | undefined;
     /**
      * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
      * 返回注销函数。listener 抛错不会阻断消息链路。
@@ -68,7 +77,7 @@ export declare class ImRuntime implements MessageGateway {
         readonly owner: string;
         readonly connected: boolean;
         readonly status: 'online' | 'offline';
-        readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+        readonly phase: AdapterEndpointPhase;
         readonly managementCapabilities: readonly EndpointManagementCapability[];
     }[];
     /**
@@ -87,7 +96,7 @@ export declare class ImRuntime implements MessageGateway {
         readonly adapter: string;
         readonly connected: boolean;
         readonly status: 'online' | 'offline';
-        readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+        readonly phase: AdapterEndpointPhase;
         readonly managementCapabilities: readonly EndpointManagementCapability[];
     } | null;
     sendEndpointMessage(input: {
@@ -102,8 +111,7 @@ export declare class ImRuntime implements MessageGateway {
     addEndpointReaction(input: {
         readonly adapter: string;
         readonly endpointKey: string;
-        readonly message?: MessageRef;
-        readonly messageId?: string;
+        readonly message: MessageRef;
         readonly emoji: string;
         readonly sceneType?: string;
         readonly channelId?: string;
@@ -111,22 +119,19 @@ export declare class ImRuntime implements MessageGateway {
     removeEndpointReaction(input: {
         readonly adapter: string;
         readonly endpointKey: string;
-        readonly message?: MessageRef;
-        readonly messageId?: string;
+        readonly message: MessageRef;
         readonly reactionId: string;
     }): Promise<void>;
     /** Activity-feedback autoRemove: recall a previously sent status message. */
     recallEndpointMessage(input: {
         readonly adapter: string;
         readonly endpointKey: string;
-        readonly message?: MessageRef;
-        readonly messageId?: string;
+        readonly message: MessageRef;
     }): Promise<void>;
     editEndpointMessage(input: {
         readonly adapter: string;
         readonly endpointKey: string;
-        readonly message?: MessageRef;
-        readonly messageId?: string;
+        readonly message: MessageRef;
         readonly content: unknown;
     }): Promise<string | null>;
     setEndpointTyping(input: {
@@ -135,10 +140,6 @@ export declare class ImRuntime implements MessageGateway {
         readonly conversation: ConversationRef;
         readonly active?: boolean;
     }): Promise<void>;
-    /**
-     * 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, endpointKey: string): EndpointManagement | null;
+    /** Run one management operation while the Endpoint generation stays leased. */
+    withEndpointManagement<T>(adapter: string, endpointKey: string, run: (management: EndpointManagement) => T | Promise<T>): Promise<T | null>;
 }

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

@@ -1,9 +1,10 @@
-import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
+import { createToken, generationAdmissionBinder, 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 { adapterFeatureId, isAdapterIndex, endpointControlOf, resolveEndpointManagement, } from '@zhin.js/adapter';
+import { isDeliveryReceipt, } from '@zhin.js/im-contract';
 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 { defaultCommandPrefixResolver, MessageDispatcher } from './message-dispatcher.js';
@@ -21,6 +22,7 @@ export class ImRuntime {
     #renderer;
     #messageListeners = new Set();
     #interactiveHandlers = [];
+    #promptClaims = new Map();
     #snapshots;
     #inboundClaim;
     #enrichSender;
@@ -45,12 +47,25 @@ export class ImRuntime {
         resources.provide(permissionHostToken, this.permissionHost);
         resources.provide(messageBusToken, this.messageBus);
     }
+    [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),
+        };
+        return Object.freeze(gateway);
+    }
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
      * 在 Command dispatch 之前路由：action 段 / 数字回跳 / 指令预填 payload。
      */
     registerInteractiveHandler(prefix, handler) {
-        const entry = Object.freeze({ prefix, handler });
+        return this.#registerInteractiveHandler(prefix, handler);
+    }
+    #registerInteractiveHandler(prefix, handler, admission) {
+        const entry = Object.freeze({ prefix, handler, admission });
         this.#interactiveHandlers.push(entry);
         return () => {
             const index = this.#interactiveHandlers.indexOf(entry);
@@ -58,6 +73,168 @@ export class ImRuntime {
                 this.#interactiveHandlers.splice(index, 1);
         };
     }
+    // ==========================================================================
+    // Prompt claim — 命令对话式交互
+    // ==========================================================================
+    #promptConversationKey(message, subjectId = message.sender?.id ?? '') {
+        const conv = message.conversation;
+        return `${conv.endpoint.adapter}:${conv.endpoint.id}:${conv.kind}:${conv.id}:${subjectId}`;
+    }
+    #resolvePromptClaim(message) {
+        const key = this.#promptConversationKey(message);
+        const claim = this.#promptClaims.get(key);
+        if (!claim)
+            return false;
+        claim.resolve(message.content);
+        return true;
+    }
+    #claimNextMessage(message, timeout, timeoutText, signal, subjectId) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(abortError(signal, timeoutText));
+                return;
+            }
+            const key = this.#promptConversationKey(message, subjectId);
+            const existing = this.#promptClaims.get(key);
+            if (existing) {
+                clearTimeout(existing.timer);
+                existing.reject(new Error('Prompt superseded'));
+            }
+            const timer = setTimeout(() => {
+                settle(undefined, new Error(timeoutText));
+            }, timeout);
+            const onAbort = () => settle(undefined, abortError(signal, timeoutText));
+            signal?.addEventListener('abort', onAbort, { once: true });
+            const settle = (value, error) => {
+                if (this.#promptClaims.get(key) !== claim)
+                    return;
+                this.#promptClaims.delete(key);
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                if (value !== undefined)
+                    resolve(value);
+                else
+                    reject(error ?? new Error(timeoutText));
+            };
+            const claim = {
+                resolve: (raw) => settle(raw),
+                reject: (error) => settle(undefined, error),
+                timer,
+            };
+            this.#promptClaims.set(key, claim);
+        });
+    }
+    #buildCommandPrompt(message, subjectId) {
+        const DEFAULT_TIMEOUT = 3 * 60 * 1000;
+        const DEFAULT_TIMEOUT_TEXT = '输入超时';
+        const claim = (timeout, timeoutText, signal) => this.#claimNextMessage(message, timeout, timeoutText, signal, subjectId);
+        const reply = (content) => message.$reply(content);
+        return {
+            async text(tips, options) {
+                await reply(tips);
+                try {
+                    return await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options?.signal);
+                }
+                catch (e) {
+                    if (options?.default !== undefined)
+                        return options.default;
+                    await reply(e.message);
+                    throw e;
+                }
+            },
+            async number(tips, options) {
+                await reply(tips);
+                try {
+                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options?.signal);
+                    return +raw;
+                }
+                catch (e) {
+                    if (options?.default !== undefined)
+                        return options.default;
+                    await reply(e.message);
+                    throw e;
+                }
+            },
+            async confirm(tips, options) {
+                const condition = options?.condition ?? 'yes';
+                await reply(`${tips}\n输入"${condition}"以确认`);
+                try {
+                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options?.signal);
+                    return raw === condition;
+                }
+                catch (e) {
+                    if (options?.default !== undefined)
+                        return options.default;
+                    await reply(e.message);
+                    throw e;
+                }
+            },
+            async list(tips, options) {
+                const separator = options?.separator ?? ',';
+                await reply(`${tips}\n值之间使用"${separator}"分隔`);
+                try {
+                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options?.signal);
+                    const type = options?.type ?? 'text';
+                    return raw.split(separator).map((v) => {
+                        if (type === 'number')
+                            return +v;
+                        if (type === 'boolean')
+                            return v === 'true';
+                        return v;
+                    });
+                }
+                catch (e) {
+                    if (options?.default !== undefined)
+                        return options.default;
+                    await reply(e.message);
+                    throw e;
+                }
+            },
+            async pick(tips, options) {
+                const items = options.options.map((o, i) => `${i + 1}.${o.label}`);
+                const separator = options.separator ?? ',';
+                if (options.multiple)
+                    items.push(`多选请用"${separator}"分隔`);
+                await reply(`${tips}\n${items.join('\n')}`);
+                try {
+                    const raw = await claim(options.timeout ?? DEFAULT_TIMEOUT, options.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options.signal);
+                    if (!options.multiple) {
+                        return options.options.find((_, i) => i + 1 === +raw)?.value;
+                    }
+                    const indices = raw.split(separator).map(Number);
+                    return options.options
+                        .filter((_, i) => indices.includes(i + 1))
+                        .map((o) => o.value);
+                }
+                catch (e) {
+                    if (options.default !== undefined)
+                        return options.default;
+                    await reply(e.message);
+                    throw e;
+                }
+            },
+        };
+    }
+    /**
+     * Bound Prompt for this conversation.
+     * `bind.subjectId` waits for that user (e.g. master) instead of the message sender.
+     */
+    createPrompt(message, bind) {
+        const subjectId = bind?.subjectId?.trim();
+        if (bind && !subjectId)
+            return undefined;
+        if (typeof message.$reply !== 'function' || !message.conversation)
+            return undefined;
+        return this.#buildCommandPrompt(message, subjectId);
+    }
+    #createPromptForSource(source) {
+        if (!source || typeof source !== 'object')
+            return undefined;
+        const msg = source;
+        if (typeof msg.$reply !== 'function' || !msg.conversation)
+            return undefined;
+        return this.#buildCommandPrompt(msg);
+    }
     /**
      * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
      * 返回注销函数。listener 抛错不会阻断消息链路。
@@ -77,6 +254,9 @@ export class ImRuntime {
         }
     }
     async receive(input) {
+        return this.#receive(input);
+    }
+    async #receive(input, admission) {
         const lease = this.#acquire();
         let active = true;
         try {
@@ -113,15 +293,20 @@ export class ImRuntime {
                     },
                 }, lease.value);
             }, enrichedSender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.message, input.endpointId, input.mentioned, input.replyTo);
+            await runHandlers(lease.value, 'message.receive', message);
             let result = Object.freeze({ matched: false });
             const claimed = await this.#inboundClaim?.(message) === true;
             if (claimed) {
                 result = Object.freeze({ matched: true, command: 'interaction', owner: requester });
             }
+            else if (this.#resolvePromptClaim(message)) {
+                result = Object.freeze({ matched: true, command: 'prompt', owner: requester });
+            }
             else {
+                const promptFactory = (source) => this.#createPromptForSource(source);
                 await runMiddleware(lease.value, message, async () => {
-                    result = await this.#dispatchInteractive(message, requester)
-                        ?? await this.#dispatcher.dispatch(message, lease.value);
+                    result = await this.#dispatchInteractive(message, requester, admission)
+                        ?? await this.#dispatcher.dispatch(message, lease.value, promptFactory);
                     const ingressRoute = resolveIngressRoute(lease.value);
                     if (!result.matched && ingressRoute) {
                         logger.debug(formatCompact({ op: 'unmatched', conv: formatConversationLog(conversation) }));
@@ -273,58 +458,59 @@ 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.endpointKey);
-        return control?.addReaction?.(legacyMessageTarget(input.message, input.messageId), input.emoji, {
+        return this.#withEndpointControl(input.adapter, input.endpointKey, (control) => control.addReaction?.(input.message, input.emoji, {
             sceneType: input.sceneType,
             channelId: input.channelId,
-        }) ?? null;
+        }) ?? null, null);
     }
     async removeEndpointReaction(input) {
-        await this.#liveEndpointControl(input.adapter, input.endpointKey)
-            ?.removeReaction?.(legacyMessageTarget(input.message, input.messageId), input.reactionId);
+        await this.#withEndpointControl(input.adapter, input.endpointKey, (control) => control.removeReaction?.(input.message, input.reactionId), undefined);
     }
     /** Activity-feedback autoRemove: recall a previously sent status message. */
     async recallEndpointMessage(input) {
-        await this.#liveEndpointControl(input.adapter, input.endpointKey)
-            ?.recall?.(legacyMessageTarget(input.message, input.messageId));
+        await this.#withEndpointControl(input.adapter, input.endpointKey, (control) => control.recall?.(input.message), undefined);
     }
     async editEndpointMessage(input) {
-        return this.#liveEndpointControl(input.adapter, input.endpointKey)
-            ?.edit?.(legacyMessageTarget(input.message, input.messageId), input.content) ?? null;
+        return this.#withEndpointControl(input.adapter, input.endpointKey, (control) => control.edit?.(input.message, input.content) ?? null, null);
     }
     async setEndpointTyping(input) {
-        await this.#liveEndpointControl(input.adapter, input.endpointKey)
-            ?.typing?.(input.conversation, input.active);
+        await this.#withEndpointControl(input.adapter, input.endpointKey, (control) => control.typing?.(input.conversation, input.active), undefined);
     }
-    #liveEndpoint(adapter, endpointKey) {
+    async #withEndpointControl(adapter, endpointKey, run, fallback) {
+        let lease;
         try {
-            const lease = this.#acquire();
-            try {
-                const endpoint = requireAdapters(lease.value).instance(adapter, endpointKey);
-                return endpoint ?? null;
-            }
-            finally {
-                lease.release();
-            }
+            lease = this.#acquire();
         }
         catch {
-            return null;
+            return fallback;
+        }
+        try {
+            const endpoint = requireAdapters(lease.value).instance(adapter, endpointKey);
+            const control = endpointControlOf(endpoint);
+            return control ? await run(control) : fallback;
+        }
+        finally {
+            lease.release();
         }
     }
-    #liveEndpointControl(adapter, endpointKey) {
-        const endpoint = this.#liveEndpoint(adapter, endpointKey);
-        return resolveEndpointControl(endpoint) ?? 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, endpointKey) {
-        const endpoint = this.#liveEndpoint(adapter, endpointKey);
-        if (!endpoint)
+    /** Run one management operation while the Endpoint generation stays leased. */
+    async withEndpointManagement(adapter, endpointKey, run) {
+        let lease;
+        try {
+            lease = this.#acquire();
+        }
+        catch {
             return null;
-        return resolveEndpointManagement(endpoint) ?? Object.freeze({});
+        }
+        try {
+            const endpoint = requireAdapters(lease.value).instance(adapter, endpointKey);
+            if (!endpoint)
+                return null;
+            return await run(resolveEndpointManagement(endpoint) ?? Object.freeze({}));
+        }
+        finally {
+            lease.release();
+        }
     }
     async #sendWithSnapshot(request, snapshot) {
         const adapter = request.conversation.endpoint.id;
@@ -381,8 +567,21 @@ export class ImRuntime {
         catch {
             return receipt ?? failedReceipt('outbound_middleware_failed');
         }
-        if (!terminalEntered)
+        if (!terminalEntered) {
+            logger.debug(formatCompact({
+                op: 'replychain_runtime_send',
+                status: 'suppressed',
+                reason: 'middleware_stopped_before_terminal',
+                conv: formatConversationLog(request.conversation),
+            }));
             return suppressedReceipt();
+        }
+        logger.debug(formatCompact({
+            op: 'replychain_runtime_send',
+            status: receipt?.status ?? 'missing',
+            code: receipt?.failure?.code,
+            conv: formatConversationLog(request.conversation),
+        }));
         return receipt ?? failedReceipt('outbound_delivery_incomplete');
     }
     #acquire() {
@@ -394,13 +593,13 @@ export class ImRuntime {
      * interactive 回跳分发（Command dispatch 之前）：action 段 / 中央 fallback
      * 数字回跳 / 指令预填 payload → prefix 最长匹配 handler。
      */
-    async #dispatchInteractive(message, requester) {
+    async #dispatchInteractive(message, requester, admission) {
         if (this.#interactiveHandlers.length === 0)
             return undefined;
         const payload = resolveRuntimeInteractivePayload(message);
         if (!payload)
             return undefined;
-        const handler = findRuntimeInteractiveHandler(this.#interactiveHandlers, payload);
+        const handler = findRuntimeInteractiveHandler(this.#interactiveHandlers.filter((entry) => !entry.admission || entry.admission === admission), payload);
         if (!handler)
             return undefined;
         const handled = await handler(message);
@@ -439,13 +638,6 @@ function isDirectHtmlConsumer(snapshot, adapter) {
     const owner = snapshot.capabilities.get(adapter)?.owner;
     return adapterTypeName(snapshot.tree.get(owner)?.packageName) === 'sandbox';
 }
-function legacyMessageTarget(message, messageId) {
-    if (message)
-        return formatLegacyMessageRef(message);
-    if (messageId)
-        return messageId;
-    throw new TypeError('message or messageId is required');
-}
 async function prepareOutboundPayload(rendered, conversation, snapshot, finalizeInteractive = false) {
     const adapter = conversation.endpoint.id;
     const directHtml = isDirectHtmlConsumer(snapshot, adapter);
@@ -529,6 +721,15 @@ async function runMiddleware(snapshot, input, terminal, target) {
     else
         await terminal();
 }
+function handlers(snapshot) {
+    const projection = snapshot.projections.get(handlerFeatureId);
+    return isHandlerIndex(projection) ? projection : undefined;
+}
+async function runHandlers(snapshot, event, ...args) {
+    const index = handlers(snapshot);
+    if (index)
+        await index.dispatch(event, ...args);
+}
 function normalizeConsoleContent(content) {
     if (typeof content === 'string')
         return content;
@@ -581,3 +782,8 @@ function flattenContent(content) {
     }
     return String(content);
 }
+function abortError(signal, fallback) {
+    if (signal?.reason instanceof Error)
+        return signal.reason;
+    return new Error(fallback);
+}

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

@@ -1,3 +1,4 @@
+import { type CommandPromptFactory } from '@zhin.js/command';
 import type { RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { Message, MessageDispatchResult } from './contracts.js';
 /**
@@ -13,5 +14,5 @@ export declare const defaultCommandPrefixResolver: CommandPrefixResolver;
 export declare class MessageDispatcher {
     private readonly resolvePrefix;
     constructor(resolvePrefix?: CommandPrefixResolver);
-    dispatch(message: Message, snapshot: RuntimeSnapshot): Promise<MessageDispatchResult>;
+    dispatch(message: Message, snapshot: RuntimeSnapshot, promptFactory?: CommandPromptFactory): Promise<MessageDispatchResult>;
 }

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

@@ -26,7 +26,7 @@ export class MessageDispatcher {
     constructor(resolvePrefix = defaultCommandPrefixResolver) {
         this.resolvePrefix = resolvePrefix;
     }
-    async dispatch(message, snapshot) {
+    async dispatch(message, snapshot, promptFactory) {
         const prefix = this.resolvePrefix(message, snapshot);
         let input = message.content.trim();
         if (prefix && !input.startsWith(prefix)) {
@@ -43,7 +43,7 @@ export class MessageDispatcher {
             ? stripCommandPrefix(message.segments, prefix)
             : undefined;
         const matchInput = structuredInput ?? input;
-        const result = await commands.dispatch(matchInput, message);
+        const result = await commands.dispatch(matchInput, message, promptFactory, prefix);
         if (result.matched && result.value !== undefined) {
             if (!result.owner)
                 throw new Error('Matched Command is missing its owner');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -60,6 +60,11 @@
       "types": "./lib/feature/middleware.d.ts",
       "development": "./src/feature/middleware.ts",
       "import": "./lib/feature/middleware.js"
+    },
+    "./feature/handler": {
+      "types": "./lib/feature/handler.d.ts",
+      "development": "./src/feature/handler.ts",
+      "import": "./lib/feature/handler.js"
     }
   },
   "files": [
@@ -70,16 +75,17 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@zhin.js/adapter": "1.1.7",
-    "@zhin.js/command": "1.0.11",
-    "@zhin.js/component": "1.0.8",
+    "@zhin.js/adapter": "1.1.9",
+    "@zhin.js/command": "1.0.13",
+    "@zhin.js/component": "1.0.10",
     "@zhin.js/database": "1.0.79",
+    "@zhin.js/feature-kit": "1.0.10",
     "@zhin.js/im-contract": "1.0.3",
     "@zhin.js/kernel": "1.0.7",
     "@zhin.js/logger": "1.0.76",
-    "@zhin.js/middleware": "1.0.8",
-    "@zhin.js/permission": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.1.5",
+    "@zhin.js/middleware": "1.0.10",
+    "@zhin.js/permission": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.6",
     "@zhin.js/schema": "1.0.73"
   },
   "peerDependencies": {
@@ -95,7 +101,7 @@
     "@types/qrcode": "^1.5.6",
     "ajv": "8.18.0",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.5.2"
+    "@zhin.js/ai": "1.5.4"
   },
   "repository": {
     "type": "git",
@@ -137,6 +143,10 @@
       {
         "package": "@zhin.js/middleware",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/feature-kit",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []