@zhin.js/core 1.5.6 → 1.5.8

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";
@@ -218,20 +218,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 +250,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 +259,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/plugin-runtime/im/im-runtime.d.ts

@@ -1,6 +1,6 @@
-import { Scope, type PluginId, 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 { OutboundRenderer } from './outbound-renderer.js';
@@ -34,14 +34,22 @@ export interface ImRuntimeOptions {
     readonly renderer?: OutboundRenderer;
     /** Process-root ingress claim (pending interaction, authentication challenge, etc.). */
     readonly inboundClaim?: (message: Message) => boolean | Promise<boolean>;
+    /**
+     * 入站 sender 增强：在构造 Message 前，将框架级角色（master / trusted）
+     * 合并到 sender.roles，使整个下游链路（命令分发、agent ingress 等）都能读到完整角色。
+     *
+     * 返回增强后的 sender（可原样返回）。缺省时 sender 保留适配器给出的平台角色。
+     */
+    readonly enrichSender?: (sender: MessageSenderRef | undefined, conversation: IncomingMessage['conversation'], snapshot: RuntimeSnapshot) => MessageSenderRef | undefined;
 }
 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。
@@ -61,7 +69,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[];
     }[];
     /**
@@ -80,7 +88,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: {
@@ -95,8 +103,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;
@@ -104,22 +111,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: {
@@ -128,10 +132,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,8 +1,8 @@
-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 { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
 import { Message, createOutboundEnvelope, } from './contracts.js';
@@ -21,14 +21,17 @@ export class ImRuntime {
     #renderer;
     #messageListeners = new Set();
     #interactiveHandlers = [];
+    #promptClaims = new Map();
     #snapshots;
     #inboundClaim;
+    #enrichSender;
     constructor(options = {}) {
         this.#dispatcher = new MessageDispatcher(options.commandPrefix === undefined
             ? defaultCommandPrefixResolver
             : () => options.commandPrefix ?? '');
         this.#renderer = options.renderer ?? new OutboundRenderer();
         this.#inboundClaim = options.inboundClaim;
+        this.#enrichSender = options.enrichSender;
     }
     attach(snapshots) {
         if (this.#snapshots && this.#snapshots !== snapshots) {
@@ -43,12 +46,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);
@@ -56,6 +72,137 @@ export class ImRuntime {
                 this.#interactiveHandlers.splice(index, 1);
         };
     }
+    // ==========================================================================
+    // Prompt claim — 命令对话式交互
+    // ==========================================================================
+    #promptConversationKey(message) {
+        const conv = message.conversation;
+        return `${conv.endpoint.adapter}:${conv.endpoint.id}:${conv.kind}:${conv.id}:${message.sender?.id ?? ''}`;
+    }
+    #resolvePromptClaim(message) {
+        const key = this.#promptConversationKey(message);
+        const claim = this.#promptClaims.get(key);
+        if (!claim)
+            return false;
+        this.#promptClaims.delete(key);
+        clearTimeout(claim.timer);
+        claim.resolve(message.content);
+        return true;
+    }
+    #claimNextMessage(message, timeout, timeoutText) {
+        return new Promise((resolve, reject) => {
+            const key = this.#promptConversationKey(message);
+            const existing = this.#promptClaims.get(key);
+            if (existing) {
+                clearTimeout(existing.timer);
+                existing.reject(new Error('Prompt superseded'));
+            }
+            const timer = setTimeout(() => {
+                this.#promptClaims.delete(key);
+                reject(new Error(timeoutText));
+            }, timeout);
+            this.#promptClaims.set(key, { resolve, reject, timer });
+        });
+    }
+    #buildCommandPrompt(message) {
+        const DEFAULT_TIMEOUT = 3 * 60 * 1000;
+        const DEFAULT_TIMEOUT_TEXT = '输入超时';
+        const claim = (timeout, timeoutText) => this.#claimNextMessage(message, timeout, timeoutText);
+        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);
+                }
+                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);
+                    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);
+                    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);
+                    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);
+                    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;
+                }
+            },
+        };
+    }
+    #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 抛错不会阻断消息链路。
@@ -75,6 +222,9 @@ export class ImRuntime {
         }
     }
     async receive(input) {
+        return this.#receive(input);
+    }
+    async #receive(input, admission) {
         const lease = this.#acquire();
         let active = true;
         try {
@@ -87,6 +237,9 @@ export class ImRuntime {
                 sender: `${input.sender?.name || 'undefined'}(${input.sender?.id || 'undefined'})`,
                 preview: truncatePreview(input.content),
             }));
+            const enrichedSender = this.#enrichSender
+                ? this.#enrichSender(input.sender, conversation, lease.value)
+                : input.sender;
             const message = new Message(conversation, input.content, lease.value.generation, (content, replyRequester = requester, targetConversation) => {
                 if (!active)
                     throw new Error('Message reply scope has ended');
@@ -98,7 +251,7 @@ export class ImRuntime {
                     requester: replyRequester,
                     content,
                     incoming: {
-                        sender: input.sender,
+                        sender: enrichedSender,
                         content: input.content,
                         segments: input.segments,
                         messageId: input.message?.id,
@@ -107,16 +260,20 @@ export class ImRuntime {
                         mentioned: input.mentioned,
                     },
                 }, lease.value);
-            }, input.sender, 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);
             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) }));
@@ -268,58 +425,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;
@@ -389,13 +547,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);
@@ -434,13 +592,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);

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);
         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.6",
+  "version": "1.5.8",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -70,16 +70,16 @@
     "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.8",
+    "@zhin.js/command": "1.0.12",
+    "@zhin.js/component": "1.0.9",
     "@zhin.js/database": "1.0.79",
     "@zhin.js/im-contract": "1.0.3",
     "@zhin.js/kernel": "1.0.7",
+    "@zhin.js/middleware": "1.0.9",
     "@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/permission": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.6",
     "@zhin.js/schema": "1.0.73"
   },
   "peerDependencies": {
@@ -95,7 +95,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.3"
   },
   "repository": {
     "type": "git",