@zhin.js/core 1.5.8 → 1.5.9

package/lib/adapter.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 可覆盖）。

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

@@ -3,6 +3,7 @@ import { MessageBus } from './message-bus.js';
 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>;
@@ -55,6 +56,13 @@ export declare class ImRuntime implements MessageGateway {
      * 在 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 抛错不会阻断消息链路。

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

@@ -4,6 +4,7 @@ import { MessageBus, messageBusToken } from './message-bus.js';
 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';
@@ -75,45 +76,64 @@ export class ImRuntime {
     // ==========================================================================
     // Prompt claim — 命令对话式交互
     // ==========================================================================
-    #promptConversationKey(message) {
+    #promptConversationKey(message, subjectId = message.sender?.id ?? '') {
         const conv = message.conversation;
-        return `${conv.endpoint.adapter}:${conv.endpoint.id}:${conv.kind}:${conv.id}:${message.sender?.id ?? ''}`;
+        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;
-        this.#promptClaims.delete(key);
-        clearTimeout(claim.timer);
         claim.resolve(message.content);
         return true;
     }
-    #claimNextMessage(message, timeout, timeoutText) {
+    #claimNextMessage(message, timeout, timeoutText, signal, subjectId) {
         return new Promise((resolve, reject) => {
-            const key = this.#promptConversationKey(message);
+            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(() => {
-                this.#promptClaims.delete(key);
-                reject(new Error(timeoutText));
+                settle(undefined, new Error(timeoutText));
             }, timeout);
-            this.#promptClaims.set(key, { resolve, reject, timer });
+            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) {
+    #buildCommandPrompt(message, subjectId) {
         const DEFAULT_TIMEOUT = 3 * 60 * 1000;
         const DEFAULT_TIMEOUT_TEXT = '输入超时';
-        const claim = (timeout, timeoutText) => this.#claimNextMessage(message, timeout, timeoutText);
+        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);
+                    return await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options?.signal);
                 }
                 catch (e) {
                     if (options?.default !== undefined)
@@ -125,7 +145,7 @@ export class ImRuntime {
             async number(tips, options) {
                 await reply(tips);
                 try {
-                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT);
+                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options?.signal);
                     return +raw;
                 }
                 catch (e) {
@@ -139,7 +159,7 @@ export class ImRuntime {
                 const condition = options?.condition ?? 'yes';
                 await reply(`${tips}\n输入"${condition}"以确认`);
                 try {
-                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT);
+                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT, options?.signal);
                     return raw === condition;
                 }
                 catch (e) {
@@ -153,7 +173,7 @@ export class ImRuntime {
                 const separator = options?.separator ?? ',';
                 await reply(`${tips}\n值之间使用"${separator}"分隔`);
                 try {
-                    const raw = await claim(options?.timeout ?? DEFAULT_TIMEOUT, options?.timeoutText ?? DEFAULT_TIMEOUT_TEXT);
+                    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')
@@ -177,7 +197,7 @@ export class ImRuntime {
                     items.push(`多选请用"${separator}"分隔`);
                 await reply(`${tips}\n${items.join('\n')}`);
                 try {
-                    const raw = await claim(options.timeout ?? DEFAULT_TIMEOUT, options.timeoutText ?? DEFAULT_TIMEOUT_TEXT);
+                    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;
                     }
@@ -195,6 +215,18 @@ export class ImRuntime {
             },
         };
     }
+    /**
+     * 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;
@@ -261,6 +293,7 @@ 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) {
@@ -534,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() {
@@ -675,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;
@@ -727,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.js

@@ -43,7 +43,7 @@ export class MessageDispatcher {
             ? stripCommandPrefix(message.segments, prefix)
             : undefined;
         const matchInput = structuredInput ?? input;
-        const result = await commands.dispatch(matchInput, message, promptFactory);
+        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.8",
+  "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,14 +75,15 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@zhin.js/adapter": "1.1.8",
-    "@zhin.js/command": "1.0.12",
-    "@zhin.js/component": "1.0.9",
+    "@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/middleware": "1.0.9",
     "@zhin.js/logger": "1.0.76",
+    "@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"
@@ -95,7 +101,7 @@
     "@types/qrcode": "^1.5.6",
     "ajv": "8.18.0",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.5.3"
+    "@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": []