@zhin.js/core 1.1.33 → 1.1.35

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

@@ -0,0 +1,1204 @@
+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, 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 { loginAssistToken } from './login-assist-host.js';
+import { LoginAssist } from '../../built/login-assist.js';
+import { sideEventSendChannel } from '../../side-event/base.js';
+import { defaultCommandPrefixResolver, MessageDispatcher } from './message-dispatcher.js';
+import { OutboundRenderer } from './outbound-renderer.js';
+import { applyOutboundInteractivePolicy, applyOutboundMarkdownPolicy, normalizeOutboundPayload, resolveOutboundInteractivePolicy, resolveOutboundMarkdownPolicy, resolveOutboundMediaPolicy, } from './outbound-segments.js';
+import { assertCanonicalSegments } from '../../built/segment-contract/assert.js';
+import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
+import { assertUserInteractionRequest, parseUserInteractionAnswer, projectUserInteraction, renderUserInteraction, } from '../../built/user-interaction.js';
+import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveConversationKey, } from './interactive.js';
+const logger = getLogger('im');
+/** @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 {
+    constructor(message) {
+        super(message);
+        this.name = 'UserInteractionTimeoutError';
+    }
+}
+class UserInteractionSupersededError extends Error {
+    constructor() {
+        super('User interaction superseded');
+        this.name = 'UserInteractionSupersededError';
+    }
+}
+class UserInteractionDeliveryError extends Error {
+    constructor(receipt) {
+        super(`User interaction delivery failed: ${receipt.failure?.code ?? receipt.status}`);
+        this.name = 'UserInteractionDeliveryError';
+    }
+}
+export class ImRuntime {
+    #dispatcher;
+    #renderer;
+    #messageListeners = new Set();
+    #interactiveHandlers = [];
+    #interactionClaims = new Map();
+    #operationSnapshot = new AsyncLocalStorage();
+    #snapshots;
+    #inboundClaim;
+    #enrichSender;
+    conversationEvents;
+    constructor(options = {}) {
+        this.#dispatcher = new MessageDispatcher(options.commandPrefix === undefined
+            ? defaultCommandPrefixResolver
+            : () => options.commandPrefix ?? '');
+        this.#renderer = options.renderer ?? new OutboundRenderer();
+        this.conversationEvents = options.conversationEvents ?? new MemoryConversationEventStore();
+        this.#inboundClaim = options.inboundClaim;
+        this.#enrichSender = options.enrichSender;
+    }
+    /** Process composition replaces the bootstrap memory store after required DB activation. */
+    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' });
+        }
+        if (reference.kind === 'message') {
+            const local = await this.conversationEvents.getMessage(reference.message);
+            if (local)
+                return Object.freeze({ status: 'resolved', reference, value: local });
+        }
+        context.signal.throwIfAborted();
+        const conversation = reference.kind === 'message' ? reference.message.conversation : reference.conversation;
+        return requireAdapters(lease.value).resolveContent(conversation.endpoint.id, reference, context);
+    }
+    async readConversationContext(conversation, consumer, throughSequence, limit = 50, excludeMessageId) {
+        if (!Number.isSafeInteger(throughSequence) || throughSequence < 0) {
+            throw new TypeError('Conversation context throughSequence must be a non-negative integer');
+        }
+        const cursor = await this.conversationEvents.getCursor(consumer, conversation);
+        const events = await this.conversationEvents.listBetween(conversation, cursor, throughSequence, limit);
+        const blocks = aggregateConversationContext(events, excludeMessageId);
+        return Object.freeze({
+            blocks: Object.freeze(blocks),
+            cursor: Math.max(cursor, throughSequence),
+        });
+    }
+    async commitConversationContext(conversation, consumer, cursor) {
+        await this.conversationEvents.commitCursor(consumer, conversation, cursor);
+    }
+    attach(snapshots) {
+        if (this.#snapshots && this.#snapshots !== snapshots) {
+            throw new Error('ImRuntime is already attached to another Root');
+        }
+        this.#snapshots = snapshots;
+    }
+    permissionHost = createPermissionHost();
+    messageBus = new MessageBus();
+    loginAssist = new LoginAssist();
+    install(resources) {
+        resources.provide(outboundMessageToken, this);
+        resources.provide(endpointEventGatewayToken, this.endpointEvents);
+        resources.provide(loginAssistToken, this.loginAssist);
+        resources.provide(permissionHostToken, this.permissionHost);
+        resources.provide(messageBusToken, this.messageBus);
+    }
+    /** The sole Adapter ingress, also installed as endpointEventGatewayToken. */
+    endpointEvents = (() => {
+        const self = this;
+        const gateway = {
+            receive: (event) => self.receiveEndpointEvent(event),
+            [generationAdmissionBinder](gate) {
+                return Object.freeze({
+                    receive: async (event) => gate.enter(() => self.receiveEndpointEvent(event, gate)),
+                });
+            },
+        };
+        return gateway;
+    })();
+    [generationAdmissionBinder](gate) {
+        const gateway = {
+            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) {
+        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);
+            if (index >= 0)
+                this.#interactiveHandlers.splice(index, 1);
+        };
+    }
+    // ==========================================================================
+    // User interaction claim — 命令/Agent 对话式交互
+    // ==========================================================================
+    #interactionConversationKey(message, subjectId = message.sender?.id ?? '') {
+        return `${conversationRefKey(message.conversation)}:${subjectId}`;
+    }
+    #resolveInteractionClaim(message) {
+        const key = this.#interactionConversationKey(message);
+        const claim = this.#interactionClaims.get(key);
+        if (!claim)
+            return false;
+        claim.resolve(resolveRuntimeInteractivePayload(message) ?? 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.#interactionConversationKey(message, subjectId);
+            const existing = this.#interactionClaims.get(key);
+            if (existing) {
+                clearTimeout(existing.timer);
+                existing.reject(new UserInteractionSupersededError());
+            }
+            const timer = setTimeout(() => {
+                settle(undefined, new UserInteractionTimeoutError(timeoutText));
+            }, timeout);
+            const onAbort = () => settle(undefined, abortError(signal, timeoutText));
+            signal?.addEventListener('abort', onAbort, { once: true });
+            const settle = (value, error) => {
+                if (this.#interactionClaims.get(key) !== claim)
+                    return;
+                this.#interactionClaims.delete(key);
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                if (value !== undefined)
+                    resolve(value);
+                else
+                    reject(error ?? new UserInteractionTimeoutError(timeoutText));
+            };
+            const claim = {
+                resolve: (raw) => settle(raw),
+                reject: (error) => settle(undefined, error),
+                timer,
+            };
+            this.#interactionClaims.set(key, claim);
+        });
+    }
+    #buildUserInteraction(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 = async (view) => {
+            const receipt = await message.$reply(renderUserInteraction(view));
+            if (receipt.status !== 'sent')
+                throw new UserInteractionDeliveryError(receipt);
+        };
+        const ask = async (request, progress) => {
+            assertUserInteractionRequest(request);
+            const timeout = request.timeout ?? DEFAULT_TIMEOUT;
+            const timeoutText = request.timeoutText ?? DEFAULT_TIMEOUT_TEXT;
+            const deadline = Date.now() + timeout;
+            const view = projectUserInteraction(request, progress);
+            await reply(view);
+            while (true) {
+                try {
+                    const raw = await claim(Math.max(1, deadline - Date.now()), timeoutText, request.signal);
+                    const result = parseUserInteractionAnswer(request, raw);
+                    if (result.ok)
+                        return result.value;
+                    await reply({
+                        ...view,
+                        tip: [request.invalidText ?? result.message, view.tip].filter(Boolean).join('\n'),
+                    });
+                }
+                catch (error) {
+                    if (error instanceof UserInteractionTimeoutError && 'default' in request && request.default !== undefined) {
+                        return request.default;
+                    }
+                    if (error instanceof UserInteractionTimeoutError) {
+                        await reply({ title: '交互已结束', description: error.message });
+                    }
+                    throw error;
+                }
+            }
+        };
+        const sequence = async (definition) => {
+            if (!definition.title.trim())
+                throw new TypeError('User interaction sequence title must not be empty');
+            const ids = new Set();
+            for (const step of definition.steps) {
+                if (!step.id.trim())
+                    throw new TypeError('User interaction sequence step id must not be empty');
+                if (ids.has(step.id))
+                    throw new TypeError(`Duplicate user interaction sequence step id: ${step.id}`);
+                ids.add(step.id);
+            }
+            const result = {};
+            for (let index = 0; index < definition.steps.length; index += 1) {
+                const step = definition.steps[index];
+                const request = {
+                    ...step,
+                    timeout: step.timeout ?? definition.timeout,
+                    timeoutText: step.timeoutText ?? definition.timeoutText,
+                    invalidText: step.invalidText ?? definition.invalidText,
+                    signal: step.signal ?? definition.signal,
+                };
+                result[step.id] = await ask(request, {
+                    title: definition.title,
+                    description: definition.description,
+                    tip: definition.tip,
+                    index: index + 1,
+                    total: definition.steps.length,
+                });
+            }
+            return Object.freeze(result);
+        };
+        return Object.freeze({ ask, sequence });
+    }
+    /**
+     * User interaction bound to this conversation.
+     * `bind.subjectId` waits for that user (e.g. master) instead of the message sender.
+     */
+    createInteraction(message, bind) {
+        const subjectId = bind?.subjectId?.trim();
+        if (bind && !subjectId)
+            return undefined;
+        if (typeof message.$reply !== 'function' || !message.conversation)
+            return undefined;
+        return this.#buildUserInteraction(message, subjectId);
+    }
+    #createInteractionForSource(source) {
+        if (!source || typeof source !== 'object')
+            return undefined;
+        const msg = source;
+        if (typeof msg.$reply !== 'function' || !msg.conversation)
+            return undefined;
+        return this.#buildUserInteraction(msg);
+    }
+    /**
+     * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
+     * 返回注销函数。listener 抛错不会阻断消息链路。
+     */
+    onMessage(listener) {
+        this.#messageListeners.add(listener);
+        return () => { this.#messageListeners.delete(listener); };
+    }
+    #emitMessage(event) {
+        for (const listener of this.#messageListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // listener 异常不得影响消息收发
+            }
+        }
+    }
+    async #receive(source, admission) {
+        const input = source.payload;
+        const lease = this.#acquire();
+        let active = true;
+        try {
+            const conversation = input.conversation;
+            const adapter = conversation.endpoint.id;
+            const requester = requireAdapters(lease.value).owner(adapter);
+            logger.debug(formatCompact({
+                op: 'receive',
+                conv: formatConversationLog(conversation),
+                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');
+                const effectiveConversation = targetConversation
+                    ? { endpoint: conversation.endpoint, ...targetConversation }
+                    : conversation;
+                return this.#sendWithSnapshot({
+                    conversation: effectiveConversation,
+                    requester: replyRequester,
+                    content,
+                    incoming: {
+                        sender: enrichedSender,
+                        content: input.content,
+                        segments: input.segments,
+                        messageId: input.message?.id,
+                        timestamp: Date.now(),
+                        endpointId: input.endpointId,
+                        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, () => {
+                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({
+                    eventId: `message:${messageRefKey(input.message)}`,
+                    conversation,
+                    timestamp: Date.now(),
+                    type: 'message.created',
+                    message: Object.freeze({
+                        ref: input.message,
+                        ...(enrichedSender ? { actor: Object.freeze({
+                                id: enrichedSender.id,
+                                ...(enrichedSender.name ? { displayName: enrichedSender.name } : {}),
+                            }) } : {}),
+                        segments: Object.freeze(input.segments?.length
+                            ? [...input.segments]
+                            : [{ type: 'text', data: { text: input.content } }]),
+                        timestamp: Date.now(),
+                        ...(input.replyTo ? { replyTo: Object.freeze({ conversation, id: input.replyTo.id }) } : {}),
+                    }),
+                }));
+                conversationSequence = appended.sequence;
+            }
+            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.#resolveInteractionClaim(message)) {
+                result = Object.freeze({ matched: true, command: 'interaction', owner: requester });
+            }
+            else {
+                const interactionFactory = (source) => this.#createInteractionForSource(source);
+                await runMiddleware(lease.value, message, async () => {
+                    const ingressRoute = resolveIngressRoute(lease.value);
+                    const preRouted = await ingressRoute?.preRoute?.(message, lease, requester, conversationSequence) === true;
+                    if (preRouted) {
+                        result = Object.freeze({ matched: true, command: 'pre-route', owner: requester });
+                        return;
+                    }
+                    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) {
+                        logger.debug(formatCompact({ op: 'unmatched', conv: formatConversationLog(conversation) }));
+                        const handled = await ingressRoute.route(message, lease, requester, conversationSequence);
+                        if (handled) {
+                            result = Object.freeze({ matched: true, command: 'ai', owner: requester });
+                        }
+                    }
+                }, 'inbound');
+            }
+            if (result.matched) {
+                logger.debug(formatCompact({
+                    op: 'dispatched',
+                    conv: formatConversationLog(conversation),
+                    command: result.command,
+                }));
+            }
+            this.#emitMessage({
+                direction: 'inbound',
+                conversation,
+                ...(input.sender !== undefined ? { sender: input.sender } : {}),
+                contentPreview: previewText(input.content),
+                ...(input.message?.id ? { messageId: input.message.id } : {}),
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        finally {
+            active = false;
+            this.#release(lease);
+        }
+    }
+    async send(request) {
+        const lease = this.#acquire();
+        try {
+            return await this.#sendWithSnapshot(request, lease.value);
+        }
+        finally {
+            this.#release(lease);
+        }
+    }
+    /** 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(withEndpointEventPayload(source, notice));
+    }
+    async #receiveRequest(source) {
+        await this.#withRequestActionScope(source.payload, async (scoped) => {
+            await this.#receiveSideEvent(withEndpointEventPayload(source, scoped));
+        });
+    }
+    async #withRequestActionScope(request, dispatch) {
+        let active = true;
+        const actions = new Set();
+        const run = (action) => {
+            if (!active)
+                throw new Error('Request action port expired with its generation operation');
+            const operation = Promise.resolve().then(action);
+            actions.add(operation);
+            void operation.then(() => actions.delete(operation), () => actions.delete(operation));
+            return operation;
+        };
+        const scoped = Object.assign(Object.create(Object.getPrototypeOf(request)), request, {
+            $approve: async (remark) => run(() => request.$approve(remark)),
+            $reject: async (reason) => run(() => request.$reject(reason)),
+        });
+        try {
+            await dispatch(scoped);
+        }
+        finally {
+            active = false;
+            await Promise.allSettled([...actions]);
+        }
+    }
+    async #receiveSystem(source) {
+        await this.#receiveSideEvent(source);
+    }
+    async #receiveSideEvent(event) {
+        const lease = this.#acquire();
+        try {
+            await this.#runHandlers(lease.value, event.name, [event]);
+        }
+        finally {
+            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);
+                }
+            }
+        }
+    }
+    /**
+     * User interaction bound to a side-event scene (private/group channel derived from
+     * `$scene_type` / `$scene_id`). Returns undefined when outbound is unavailable.
+     */
+    #createInteractionForSideEvent(payload, snapshot) {
+        const adapter = String(payload.$adapter);
+        const endpointKey = String(payload.$endpoint);
+        if (!adapter || !endpointKey)
+            return undefined;
+        const channel = sideEventSendChannel(payload);
+        const conversation = Object.freeze({
+            endpoint: Object.freeze({ adapter, id: endpointKey }),
+            kind: channel.type,
+            id: channel.id || endpointKey,
+        });
+        const requester = snapshot.root;
+        const source = Object.freeze({
+            conversation,
+            ...(payload.$actor?.id
+                ? { sender: Object.freeze({ id: payload.$actor.id }) }
+                : {}),
+            $reply: (content) => this.#sendWithSnapshot({
+                conversation,
+                requester,
+                content,
+            }, snapshot),
+        });
+        return this.#buildUserInteraction(source);
+    }
+    async #runHandlers(snapshot, event, args) {
+        const index = handlers(snapshot);
+        if (!index)
+            return;
+        const options = {
+            resolveInteraction: (name, interactionArgs) => {
+                const context = interactionArgs[0];
+                const payload = context?.payload;
+                if (name === 'message.receive' && payload instanceof Message) {
+                    return this.createInteraction(payload);
+                }
+                if (name === 'notice.receive'
+                    || name === 'request.receive'
+                    || name === 'system.receive') {
+                    return this.#createInteractionForSideEvent(payload, snapshot);
+                }
+                return undefined;
+            },
+        };
+        await index.dispatch(event, args, options);
+    }
+    /** Console `endpoint.list` — empty until Adapter Feature projection is ready. */
+    listEndpoints() {
+        try {
+            const lease = this.#acquire();
+            try {
+                return requireAdapters(lease.value).describe().map((row) => Object.freeze({
+                    id: String(row.id),
+                    name: row.name,
+                    // adapter 列显示平台类型（owner 包名去 scope/adapter- 前缀），不是 slot localName
+                    adapter: adapterTypeName(lease.value.tree.get(row.owner)?.packageName) ?? row.name,
+                    owner: row.owner,
+                    connected: row.connected,
+                    status: row.status,
+                    phase: row.phase,
+                    operations: row.operations,
+                    managementCapabilities: row.managementCapabilities,
+                }));
+            }
+            finally {
+                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` 已不存在）。
+     */
+    inventory() {
+        try {
+            const lease = this.#acquire();
+            try {
+                const plugins = [...lease.value.tree.values()]
+                    .filter((node) => node.parent !== undefined).length;
+                const endpoints = requireAdapters(lease.value).describe();
+                return Object.freeze({
+                    plugins,
+                    endpoints: Object.freeze({
+                        total: endpoints.length,
+                        online: endpoints.filter((endpoint) => endpoint.status === 'online').length,
+                    }),
+                });
+            }
+            finally {
+                this.#release(lease);
+            }
+        }
+        catch {
+            return Object.freeze({
+                plugins: 0,
+                endpoints: Object.freeze({ total: 0, online: 0 }),
+            });
+        }
+    }
+    getEndpoint(adapter, endpointKey) {
+        try {
+            const lease = this.#acquire();
+            try {
+                const index = requireAdapters(lease.value);
+                const id = index.resolve(adapter, endpointKey);
+                if (!id)
+                    return null;
+                const row = index.describe().find((item) => item.id === id);
+                if (!row)
+                    return null;
+                // adapter 与 listEndpoints 对齐：平台类型（owner 包名去 scope/adapter- 前缀），
+                // 不是 live name（如 ICQQ uin）。此前误写 row.name 导致 endpoint.info 与 list 不一致。
+                return Object.freeze({
+                    name: row.name,
+                    adapter: adapterTypeName(lease.value.tree.get(row.owner)?.packageName) ?? row.name,
+                    connected: row.connected,
+                    status: row.status,
+                    phase: row.phase,
+                    operations: row.operations,
+                    managementCapabilities: row.managementCapabilities,
+                });
+            }
+            finally {
+                this.#release(lease);
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    async sendEndpointMessage(input) {
+        const lease = this.#acquire();
+        try {
+            const index = requireAdapters(lease.value);
+            const resolved = index.resolve(input.adapter, input.endpointKey);
+            if (!resolved)
+                throw new Error('endpoint not found');
+            const requester = index.owner(resolved);
+            const conversation = {
+                endpoint: { id: String(resolved), adapter: String(requester) },
+                ...input.conversation,
+            };
+            const content = normalizeConsoleContent(input.content);
+            const result = await this.#sendWithSnapshot({
+                conversation,
+                requester,
+                content,
+            }, lease.value);
+            return { messageId: result.message?.id ?? '' };
+        }
+        finally {
+            this.#release(lease);
+        }
+    }
+    /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
+    async addEndpointReaction(input) {
+        return this.#withEndpointControl(input.adapter, input.endpointKey, 'reaction', (control) => control.addReaction?.(input.message, input.emoji, {
+            sceneType: input.sceneType,
+            channelId: input.channelId,
+        }) ?? null, null);
+    }
+    async removeEndpointReaction(input) {
+        await this.#withEndpointControl(input.adapter, input.endpointKey, 'reaction', (control) => control.removeReaction?.(input.message, input.reactionId), undefined);
+    }
+    /** Activity-feedback autoRemove: recall a previously sent status message. */
+    async recallEndpointMessage(input) {
+        await this.#withEndpointControl(input.adapter, input.endpointKey, 'recall', (control) => control.recall?.(input.message), undefined);
+    }
+    async editEndpointMessage(input) {
+        return this.#withEndpointControl(input.adapter, input.endpointKey, 'edit', (control) => control.edit?.(input.message, input.content) ?? null, null);
+    }
+    async setEndpointTyping(input) {
+        await this.#withEndpointControl(input.adapter, input.endpointKey, 'typing', (control) => control.typing?.(input.conversation, input.active), undefined);
+    }
+    async #withEndpointControl(adapter, endpointKey, operation, run, fallback) {
+        let lease;
+        try {
+            lease = this.#acquire();
+        }
+        catch {
+            return fallback;
+        }
+        try {
+            const index = requireAdapters(lease.value);
+            const id = index.resolve(adapter, endpointKey);
+            const control = id ? index.control(id, operation) : undefined;
+            return control ? await run(control) : fallback;
+        }
+        finally {
+            this.#release(lease);
+        }
+    }
+    /** Run one management operation while the Endpoint generation stays leased. */
+    async withEndpointManagement(adapter, endpointKey, run) {
+        let lease;
+        try {
+            lease = this.#acquire();
+        }
+        catch {
+            return null;
+        }
+        try {
+            const endpoint = requireAdapters(lease.value).connection(adapter, endpointKey);
+            if (!endpoint)
+                return null;
+            return await run(resolveEndpointManagement(endpoint) ?? Object.freeze({}));
+        }
+        finally {
+            this.#release(lease);
+        }
+    }
+    async #sendWithSnapshot(request, snapshot) {
+        const adapter = request.conversation.endpoint.id;
+        let initialPayload;
+        try {
+            const rendered = await this.#renderer.render(request.content, request.requester, snapshot, request.conversation, request.incoming);
+            initialPayload = await prepareOutboundPayload(rendered, request.conversation, snapshot);
+        }
+        catch {
+            return rejectedReceipt('outbound_payload_rejected');
+        }
+        let adapters;
+        try {
+            adapters = requireAdapters(snapshot);
+        }
+        catch (error) {
+            return receiptFromEndpointError(error);
+        }
+        const envelope = createOutboundEnvelope({
+            conversation: request.conversation,
+            requester: request.requester,
+            generation: snapshot.generation,
+            clientAdapter: adapters.clientAdapter(adapter),
+        }, initialPayload, () => adapters.clientById(adapter));
+        let terminalEntered = false;
+        let receipt;
+        try {
+            await runMiddleware(snapshot, envelope, async () => {
+                terminalEntered = true;
+                let payload;
+                try {
+                    payload = await prepareOutboundPayload(envelope.payload, request.conversation, snapshot, true);
+                }
+                catch {
+                    receipt = rejectedReceipt('outbound_payload_rejected');
+                    return;
+                }
+                try {
+                    const result = await requireAdapters(snapshot).send(adapter, {
+                        conversation: request.conversation,
+                        payload,
+                    });
+                    receipt = receiptFromEndpointResult(result, request.conversation);
+                }
+                catch (error) {
+                    receipt = receiptFromEndpointError(error);
+                }
+                if (receipt?.status === 'sent') {
+                    if (receipt.message?.id) {
+                        const segments = conversationSegmentsFromContent(request.content);
+                        await this.conversationEvents.append(Object.freeze({
+                            eventId: `message:${messageRefKey(receipt.message)}`,
+                            conversation: request.conversation,
+                            timestamp: Date.now(),
+                            type: 'message.created',
+                            message: Object.freeze({
+                                ref: receipt.message,
+                                segments,
+                                timestamp: Date.now(),
+                            }),
+                        }));
+                    }
+                    this.#emitMessage({
+                        direction: 'outbound',
+                        conversation: request.conversation,
+                        requester: request.requester,
+                        contentPreview: previewText(payload),
+                        ...(receipt.message?.id
+                            ? { messageId: receipt.message.id }
+                            : {}),
+                        timestamp: Date.now(),
+                    });
+                }
+            }, 'outbound');
+        }
+        catch {
+            return receipt ?? failedReceipt('outbound_middleware_failed');
+        }
+        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() {
+        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。
+     */
+    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.filter((entry) => !entry.admission || entry.admission === admission), payload);
+        if (!handler)
+            return undefined;
+        const handled = await handler(message);
+        return handled
+            ? Object.freeze({ matched: true, command: 'interactive', owner: requester })
+            : undefined;
+    }
+}
+function conversationEventFromNotice(notice) {
+    const sceneType = notice.$scene_type;
+    const kind = sceneType === 'group' ? 'group'
+        : sceneType === 'channel' ? 'channel'
+            : sceneType === 'friend' || sceneType === 'private' ? 'private'
+                : undefined;
+    if (!kind || !notice.$scene_id || !notice.$id)
+        return undefined;
+    const conversation = Object.freeze({
+        endpoint: Object.freeze({ adapter: String(notice.$adapter), id: String(notice.$endpoint) }),
+        kind,
+        id: String(notice.$scene_id),
+    });
+    const actor = notice.$actor?.id
+        ? Object.freeze({ id: String(notice.$actor.id), ...(notice.$actor.name ? { displayName: notice.$actor.name } : {}) })
+        : undefined;
+    const target = notice.$target?.id
+        ? Object.freeze({ id: String(notice.$target.id), ...(notice.$target.name ? { displayName: notice.$target.name } : {}) })
+        : undefined;
+    const base = Object.freeze({
+        eventId: `notice:${conversationRefKey(conversation)}:${String(notice.$id)}`,
+        conversation,
+        timestamp: notice.$timestamp,
+    });
+    switch (notice.$sub_type) {
+        case 'member_increase':
+        case 'increase':
+            return target ? Object.freeze({ ...base, type: 'member.joined', member: target, ...(actor ? { actor } : {}) }) : undefined;
+        case 'member_decrease':
+            return target ? Object.freeze({ ...base, type: 'member.left', member: target, ...(actor ? { actor } : {}), reason: actor ? 'removed' : 'left' }) : undefined;
+        case 'ban':
+            if (!target)
+                return undefined;
+            return notice.$duration_seconds === 0
+                ? Object.freeze({ ...base, type: 'member.unmuted', member: target, ...(actor ? { actor } : {}) })
+                : Object.freeze({ ...base, type: 'member.muted', member: target, ...(actor ? { actor } : {}), durationSeconds: notice.$duration_seconds ?? 0 });
+        case 'admin_change':
+            return target && notice.$role && typeof notice.$enabled === 'boolean'
+                ? Object.freeze({ ...base, type: 'member.role_changed', member: target, ...(actor ? { actor } : {}), role: notice.$role, enabled: notice.$enabled })
+                : undefined;
+        case 'recall':
+            return notice.$message_id
+                ? Object.freeze({ ...base, type: 'message.recalled', message: Object.freeze({ conversation, id: notice.$message_id }), ...(actor ? { actor } : {}) })
+                : undefined;
+        case 'emoji_reaction':
+            return notice.$message_id && notice.$reaction && notice.$operation
+                ? Object.freeze({ ...base, type: 'message.reaction_changed', message: Object.freeze({ conversation, id: notice.$message_id }), ...(actor ? { actor } : {}), reaction: notice.$reaction, operation: notice.$operation })
+                : undefined;
+        case 'poke':
+            return Object.freeze({ ...base, type: 'conversation.poked', ...(actor ? { actor } : {}), ...(target ? { target } : {}) });
+        default:
+            return undefined;
+    }
+}
+function describeConversationEvent(event) {
+    const actor = 'actor' in event && event.actor ? `${event.actor.displayName ?? event.actor.id} (${event.actor.id})` : undefined;
+    switch (event.type) {
+        case 'message.recalled': return `${actor ?? 'Someone'} recalled message ${event.message.id}.`;
+        case 'message.reaction_changed': return `${actor ?? 'Someone'} ${event.operation} reaction ${event.reaction} on message ${event.message.id}.`;
+        case 'conversation.poked': return `${actor ?? 'Someone'} poked ${event.target ? `${event.target.displayName ?? event.target.id} (${event.target.id})` : 'someone'}.`;
+        case 'member.joined': return `${event.member.displayName ?? event.member.id} (${event.member.id}) joined the conversation.`;
+        case 'member.left': return `${event.member.displayName ?? event.member.id} (${event.member.id}) left the conversation (${event.reason ?? 'left'}).`;
+        case 'member.muted': return `${event.member.displayName ?? event.member.id} (${event.member.id}) was muted for ${event.durationSeconds} seconds${actor ? ` by ${actor}` : ''}.`;
+        case 'member.unmuted': return `${event.member.displayName ?? event.member.id} (${event.member.id}) was unmuted${actor ? ` by ${actor}` : ''}.`;
+        case 'member.role_changed': return `${event.member.displayName ?? event.member.id} (${event.member.id}) role ${event.role} was ${event.enabled ? 'enabled' : 'disabled'}${actor ? ` by ${actor}` : ''}.`;
+        case 'message.created': return '';
+    }
+}
+function describeConversationMessage(message) {
+    const actor = message.actor
+        ? `${message.actor.displayName ?? message.actor.id} (${message.actor.id})`
+        : undefined;
+    if (!actor)
+        return '';
+    const text = segmentsToPlainText(message.segments).trim();
+    const attachmentTypes = [...new Set(message.segments
+            .filter((segment) => segment.type !== 'text' && segment.type !== 'mention' && segment.type !== 'at')
+            .map((segment) => segment.type))];
+    const attachmentNote = attachmentTypes.length > 0
+        ? ` [message also contains ${attachmentTypes.join(', ')} data; inspect its reference before relying on that content]`
+        : '';
+    return `${actor}: ${text || '(no plain-text content)'}${attachmentNote}`;
+}
+function aggregateConversationContext(events, excludeMessageId) {
+    const ordinary = [];
+    const noisy = new Map();
+    for (const { sequence, event } of events) {
+        if (event.type === 'message.created') {
+            if (event.message.ref.id === excludeMessageId)
+                continue;
+            const text = describeConversationMessage(event.message);
+            if (!text)
+                continue;
+            ordinary.push(Object.freeze({
+                kind: 'conversation_event',
+                sequence,
+                eventType: event.type,
+                text,
+            }));
+            continue;
+        }
+        if (event.type === 'message.reaction_changed' || event.type === 'conversation.poked') {
+            const key = event.type === 'message.reaction_changed'
+                ? `${event.type}:${event.message.id}:${event.actor?.id ?? ''}:${event.reaction}:${event.operation}`
+                : `${event.type}:${event.actor?.id ?? ''}:${event.target?.id ?? ''}`;
+            const previous = noisy.get(key);
+            noisy.set(key, { sequence, event, count: (previous?.count ?? 0) + 1 });
+            continue;
+        }
+        ordinary.push(Object.freeze({
+            kind: 'conversation_event',
+            sequence,
+            eventType: event.type,
+            text: describeConversationEvent(event),
+        }));
+    }
+    for (const { sequence, event, count } of noisy.values()) {
+        ordinary.push(Object.freeze({
+            kind: 'conversation_event',
+            sequence,
+            eventType: event.type,
+            text: `${describeConversationEvent(event)}${count > 1 ? ` (${count} similar events.)` : ''}`,
+        }));
+    }
+    ordinary.sort((left, right) => left.sequence - right.sequence);
+    return Object.freeze(ordinary);
+}
+function resolveIngressRoute(snapshot) {
+    const candidate = snapshot.resources.get(snapshot.root)?.get(ingressRouteToken.id);
+    return candidate
+        && typeof candidate === 'object'
+        && typeof candidate.route === 'function'
+        ? candidate
+        : undefined;
+}
+function requireAdapters(snapshot) {
+    const projection = snapshot.projections.get(adapterFeatureId);
+    if (!isAdapterIndex(projection)) {
+        throw new Error('Adapter Feature projection is not installed');
+    }
+    return projection;
+}
+/** Root resources 上的可选 html-renderer Host（未安装时降级为文本）。 */
+function resolveHtmlRenderer(snapshot) {
+    const host = snapshot.resources.get(snapshot.root)?.get(htmlRendererToken.id);
+    return host && typeof host.render === 'function'
+        ? host
+        : undefined;
+}
+/**
+ * Sandbox（控制台 UI）按设计直接消费 html 段，不做 html→image/text 规范化。
+ * 通过 adapter 能力 slot 的 owner 包名判断平台类型。
+ */
+function isDirectHtmlConsumer(snapshot, adapter) {
+    const owner = snapshot.capabilities.get(adapter)?.owner;
+    return adapterTypeName(snapshot.tree.get(owner)?.packageName) === 'sandbox';
+}
+async function prepareOutboundPayload(rendered, conversation, snapshot, finalizeInteractive = false) {
+    const adapter = conversation.endpoint.id;
+    const directHtml = isDirectHtmlConsumer(snapshot, adapter);
+    const markdownResolved = applyOutboundMarkdownPolicy(rendered, resolveOutboundMarkdownPolicy(adapter, snapshot));
+    let payload = directHtml
+        ? markdownResolved
+        : await normalizeOutboundPayload(markdownResolved, resolveHtmlRenderer(snapshot), {
+            mediaPolicy: resolveOutboundMediaPolicy(adapter, snapshot),
+        });
+    if (finalizeInteractive) {
+        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveConversationKey(conversation), map));
+    }
+    if (!directHtml && Array.isArray(payload))
+        assertCanonicalSegments(payload);
+    return payload;
+}
+function receiptFromEndpointResult(messageId, conversation) {
+    return Object.freeze({
+        status: 'sent',
+        message: Object.freeze({ conversation, id: messageId }),
+    });
+}
+function receiptFromEndpointError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/Unknown Adapter Endpoint|does not support outbound/u.test(message)) {
+        return unsupportedReceipt('outbound_unsupported');
+    }
+    if (/not active/u.test(message))
+        return failedReceipt('endpoint_inactive', true);
+    return failedReceipt('endpoint_send_failed', true);
+}
+function suppressedReceipt() {
+    return Object.freeze({ status: 'suppressed' });
+}
+function unsupportedReceipt(code) {
+    return Object.freeze({
+        status: 'unsupported',
+        failure: Object.freeze({ code, message: 'Outbound delivery is not supported.' }),
+    });
+}
+function rejectedReceipt(code) {
+    return Object.freeze({
+        status: 'rejected',
+        failure: Object.freeze({ code, message: 'Outbound payload was rejected.' }),
+    });
+}
+function failedReceipt(code, retryable = false) {
+    return Object.freeze({
+        status: 'failed',
+        failure: Object.freeze({
+            code,
+            message: 'Outbound delivery failed.',
+            ...(retryable ? { retryable: true } : {}),
+        }),
+    });
+}
+/** `@zhin.js/adapter-icqq` → `icqq`；非 adapter 包名原样返回。 */
+function adapterTypeName(packageName) {
+    if (!packageName)
+        return undefined;
+    return packageName.replace(/^@[^/]+\/adapter-/, '');
+}
+function middleware(snapshot) {
+    const projection = snapshot.projections.get(middlewareFeatureId);
+    return isMiddlewareIndex(projection) ? projection : undefined;
+}
+async function runMiddleware(snapshot, input, terminal, target) {
+    const index = middleware(snapshot);
+    if (index)
+        await index.run(input, terminal, target);
+    else
+        await terminal();
+}
+function handlers(snapshot) {
+    const projection = snapshot.projections.get(handlerFeatureId);
+    return isHandlerIndex(projection) ? projection : undefined;
+}
+function normalizeConsoleContent(content) {
+    if (typeof content === 'string')
+        return content;
+    // Array content passes through untouched, matching the legacy console RPC
+    // contract (element arrays must not be stringified to '[object Object]').
+    if (Array.isArray(content))
+        return content;
+    return String(content);
+}
+/** 日志用会话摘要（`kind:id@parentKind:parentId#threadId`），不拼 legacy target。 */
+function formatConversationLog(conversation) {
+    const base = `${conversation.kind}:${conversation.id}`;
+    const parent = conversation.parent
+        ? `@${conversation.parent.kind}:${conversation.parent.id}`
+        : '';
+    const thread = conversation.threadId ? `#${conversation.threadId}` : '';
+    return `${base}${parent}${thread}`;
+}
+/** 消息内容 → 预览文本（截断 200 字）；wire 段取 `data.text`，其余段记 `[type]`。 */
+function previewText(content) {
+    const text = flattenContent(content);
+    return text.length > messagePreviewLimit
+        ? `${text.slice(0, messagePreviewLimit)}…`
+        : text;
+}
+function flattenContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content == null)
+        return '';
+    if (Array.isArray(content)) {
+        return content.map((item) => flattenContent(item)).join('');
+    }
+    if (typeof content === 'object') {
+        const record = content;
+        const data = record.data;
+        if (typeof record.type === 'string') {
+            if (data && typeof data.text === 'string')
+                return data.text;
+            return `[${record.type}]`;
+        }
+        if (typeof record.text === 'string')
+            return record.text;
+        try {
+            return JSON.stringify(content) ?? '';
+        }
+        catch {
+            return String(content);
+        }
+    }
+    return String(content);
+}
+function conversationSegmentsFromContent(content) {
+    if (Array.isArray(content)) {
+        try {
+            assertCanonicalSegments(content);
+            return Object.freeze([...content]);
+        }
+        catch {
+            // Fall through to a truthful text projection of non-canonical output.
+        }
+    }
+    return Object.freeze([{ type: 'text', data: Object.freeze({ text: flattenContent(content) }) }]);
+}
+function abortError(signal, fallback) {
+    if (signal?.reason instanceof Error)
+        return signal.reason;
+    return new Error(fallback);
+}
+function withEndpointEventPayload(source, payload) {
+    return Object.freeze({
+        name: source.name,
+        payload,
+        endpoint: source.endpoint,
+        client: source.client,
+    });
+}