@zhin.js/core 1.5.11 → 1.5.13

package/lib/built/user-interaction.js

@@ -0,0 +1,248 @@
+/** Fail early for interaction definitions that could never produce an unambiguous answer. */
+export function assertUserInteractionRequest(request) {
+    if (!request.title.trim())
+        throw new TypeError('User interaction title must not be empty');
+    if (request.timeout !== undefined && (!Number.isFinite(request.timeout) || request.timeout <= 0)) {
+        throw new RangeError('User interaction timeout must be a positive finite number');
+    }
+    if (request.type === 'text' && !validRange(request.minLength, request.maxLength)) {
+        throw new RangeError('User interaction text length range is invalid');
+    }
+    if (request.type === 'number' && !validBounds(request.min, request.max)) {
+        throw new RangeError('User interaction number range is invalid');
+    }
+    if (request.type === 'select' || request.type === 'multiselect') {
+        if (request.options.length === 0)
+            throw new TypeError('User interaction options must not be empty');
+        const labels = new Set();
+        for (const option of request.options) {
+            const label = option.label.trim().toLocaleLowerCase();
+            if (!label)
+                throw new TypeError('User interaction option label must not be empty');
+            if (labels.has(label))
+                throw new TypeError(`Duplicate user interaction option label: ${option.label}`);
+            labels.add(label);
+        }
+    }
+    if (request.type === 'multiselect') {
+        if (request.separator === '')
+            throw new TypeError('User interaction separator must not be empty');
+        if (!validRange(request.minSelections, request.maxSelections)) {
+            throw new RangeError('User interaction selection range is invalid');
+        }
+    }
+    if (request.type === 'list') {
+        if (request.separator === '')
+            throw new TypeError('User interaction separator must not be empty');
+        if (!validRange(request.minItems, request.maxItems)) {
+            throw new RangeError('User interaction list length range is invalid');
+        }
+    }
+}
+/** Project semantic content into canonical Markdown + keyboard segments. */
+export function renderUserInteraction(view) {
+    const markdown = [
+        `### ${view.title}`,
+        view.description?.trim(),
+        view.tip?.trim() ? quoteTip(view.tip.trim()) : undefined,
+    ].filter((part) => !!part).join('\n\n');
+    const actions = view.actions ?? [];
+    if (actions.length === 0) {
+        return [{ type: 'markdown', data: { content: markdown } }];
+    }
+    const buttons = actions.map((action, index) => ({
+        id: `interaction-${index + 1}`,
+        label: action.label,
+        payload: action.value,
+        ...(action.style ? { style: action.style } : {}),
+        mode: 'command',
+        command: { enter: true, reply: false },
+    }));
+    return [
+        { type: 'markdown', data: { content: markdown } },
+        {
+            type: 'keyboard',
+            data: {
+                rows: chunk(buttons, 5),
+                fallback: {
+                    hint: '也可以直接回复对应内容。',
+                    map: Object.fromEntries(actions.map((action, index) => [String(index + 1), action.value])),
+                },
+            },
+        },
+    ];
+}
+/** Derive presentation and controls from one discriminated request. */
+export function projectUserInteraction(request, progress) {
+    const instruction = instructionFor(request);
+    const optionList = request.type === 'select' || request.type === 'multiselect'
+        ? renderOptions(request.options)
+        : undefined;
+    const optionsHaveDescriptions = request.type === 'select' || request.type === 'multiselect'
+        ? request.options.some((option) => !!option.description)
+        : false;
+    const actions = actionsFor(request);
+    const stepDescription = [
+        progress ? `**${progress.index}/${progress.total} · ${request.title}**` : undefined,
+        request.description,
+        optionList && (!actions || optionsHaveDescriptions) ? optionList : undefined,
+    ].filter((part) => !!part).join('\n\n');
+    return Object.freeze({
+        title: progress?.title ?? request.title,
+        description: progress
+            ? [progress.description, stepDescription].filter(Boolean).join('\n\n')
+            : stepDescription || undefined,
+        tip: [request.tip, instruction, progress?.tip].filter(Boolean).join('\n'),
+        ...(actions ? { actions: Object.freeze(actions) } : {}),
+    });
+}
+/** Parse and validate one user reply without transport knowledge. */
+export function parseUserInteractionAnswer(request, rawInput) {
+    const raw = rawInput.trim();
+    switch (request.type) {
+        case 'text': {
+            if (raw.length < (request.minLength ?? 0))
+                return invalid(`请至少输入 ${request.minLength} 个字符`);
+            if (request.maxLength !== undefined && raw.length > request.maxLength) {
+                return invalid(`请不要超过 ${request.maxLength} 个字符`);
+            }
+            if (request.pattern) {
+                request.pattern.lastIndex = 0;
+                if (!request.pattern.test(raw))
+                    return invalid('输入格式不正确');
+            }
+            return valid(raw);
+        }
+        case 'number': {
+            const value = Number(raw);
+            if (!raw || !Number.isFinite(value))
+                return invalid('请输入有效数字');
+            if (request.integer && !Number.isInteger(value))
+                return invalid('请输入整数');
+            if (request.min !== undefined && value < request.min)
+                return invalid(`请输入不小于 ${request.min} 的数字`);
+            if (request.max !== undefined && value > request.max)
+                return invalid(`请输入不大于 ${request.max} 的数字`);
+            return valid(value);
+        }
+        case 'confirm': {
+            const normalized = raw.toLocaleLowerCase();
+            const confirmLabel = request.confirmLabel?.trim().toLocaleLowerCase();
+            const cancelLabel = request.cancelLabel?.trim().toLocaleLowerCase();
+            if (CONFIRM_VALUES.has(normalized) || (confirmLabel && normalized === confirmLabel))
+                return valid(true);
+            if (CANCEL_VALUES.has(normalized) || (cancelLabel && normalized === cancelLabel))
+                return valid(false);
+            return invalid('请选择确认或取消');
+        }
+        case 'select': {
+            const option = resolveOption(request.options, raw);
+            return option ? valid(option.value) : invalid('请选择一个有效选项');
+        }
+        case 'multiselect': {
+            const separator = request.separator ?? ',';
+            const tokens = raw.split(separator).map((token) => token.trim()).filter(Boolean);
+            const selected = uniqueOptions(tokens.map((token) => resolveOption(request.options, token)));
+            if (selected.length !== tokens.length)
+                return invalid('多选中包含无效选项');
+            if (selected.length < (request.minSelections ?? 0))
+                return invalid(`请至少选择 ${request.minSelections} 项`);
+            if (request.maxSelections !== undefined && selected.length > request.maxSelections) {
+                return invalid(`请最多选择 ${request.maxSelections} 项`);
+            }
+            return valid(Object.freeze(selected.map((option) => option.value)));
+        }
+        case 'list': {
+            const separator = request.separator ?? ',';
+            const tokens = raw.split(separator).map((token) => token.trim()).filter(Boolean);
+            if (tokens.length < (request.minItems ?? 0))
+                return invalid(`请至少输入 ${request.minItems} 项`);
+            if (request.maxItems !== undefined && tokens.length > request.maxItems)
+                return invalid(`请最多输入 ${request.maxItems} 项`);
+            if (request.valueType === 'number') {
+                const values = tokens.map(Number);
+                return values.every(Number.isFinite) ? valid(Object.freeze(values)) : invalid('列表中包含无效数字');
+            }
+            if (request.valueType === 'boolean') {
+                const values = tokens.map(parseBoolean);
+                return values.every((value) => value !== undefined)
+                    ? valid(Object.freeze(values))
+                    : invalid('布尔列表只接受 true/false、yes/no 或 是/否');
+            }
+            return valid(Object.freeze(tokens));
+        }
+    }
+}
+function actionsFor(request) {
+    if (request.type === 'confirm') {
+        return [
+            { label: request.confirmLabel ?? '确认', value: 'yes', style: 'primary' },
+            { label: request.cancelLabel ?? '取消', value: 'no', style: 'danger' },
+        ];
+    }
+    if (request.type === 'select' && request.options.length <= 10) {
+        return request.options.map((option, index) => ({ label: option.label, value: String(index + 1), style: 'secondary' }));
+    }
+    return undefined;
+}
+function instructionFor(request) {
+    switch (request.type) {
+        case 'confirm': return '请选择确认或取消。';
+        case 'select': return '可以点击按钮，或回复序号/选项名称。';
+        case 'multiselect': return `回复序号或选项名称，多项用“${request.separator ?? ','}”分隔。`;
+        case 'list': return `多项用“${request.separator ?? ','}”分隔。`;
+        default: return undefined;
+    }
+}
+function renderOptions(options) {
+    return options.map((option, index) => `${index + 1}. ${option.label}${option.description ? ` — ${option.description}` : ''}`).join('\n');
+}
+function resolveOption(options, raw) {
+    const index = Number(raw);
+    if (Number.isInteger(index) && index >= 1 && index <= options.length)
+        return options[index - 1];
+    const normalized = raw.toLocaleLowerCase();
+    return options.find((option) => option.label.trim().toLocaleLowerCase() === normalized);
+}
+function uniqueOptions(options) {
+    const result = [];
+    for (const option of options)
+        if (option && !result.includes(option))
+            result.push(option);
+    return result;
+}
+function parseBoolean(raw) {
+    const normalized = raw.toLocaleLowerCase();
+    if (CONFIRM_VALUES.has(normalized))
+        return true;
+    if (CANCEL_VALUES.has(normalized))
+        return false;
+    return undefined;
+}
+function quoteTip(tip) {
+    return tip.split('\n').map((line) => `> 💡 ${line}`).join('\n');
+}
+function valid(value) {
+    return Object.freeze({ ok: true, value });
+}
+function invalid(message) {
+    return Object.freeze({ ok: false, message });
+}
+function validRange(minimum, maximum) {
+    return (minimum === undefined || (Number.isFinite(minimum) && minimum >= 0))
+        && (maximum === undefined || (Number.isFinite(maximum) && maximum >= 0))
+        && (minimum === undefined || maximum === undefined || minimum <= maximum);
+}
+function validBounds(minimum, maximum) {
+    return (minimum === undefined || Number.isFinite(minimum))
+        && (maximum === undefined || Number.isFinite(maximum))
+        && (minimum === undefined || maximum === undefined || minimum <= maximum);
+}
+const CONFIRM_VALUES = new Set(['1', 'y', 'yes', 'true', '是', '确认', '同意']);
+const CANCEL_VALUES = new Set(['2', 'n', 'no', 'false', '否', '取消', '拒绝']);
+function chunk(items, size) {
+    const rows = [];
+    for (let index = 0; index < items.length; index += size)
+        rows.push(items.slice(index, index + size));
+    return rows;
+}

package/lib/feature/handler.d.ts

@@ -1,5 +1,5 @@
 /** Authoring API for Handler Feature — implementation in `@zhin.js/handler`. */
-export { defineHandler, parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, type HandlerEventMap, type HandlerDefinition, type HandlerDescriptor, } from '@zhin.js/handler';
+export { defineHandler, parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, type HandlerEventMap, type HandlerDefinition, type HandlerDescriptor, type HandlerContext, type HandlerDispatchOptions, } from '@zhin.js/handler';
 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];

package/lib/feature/handler.js

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

package/lib/im-scene.js

@@ -68,10 +68,8 @@ export function messageToIMDeliveryTarget(message) {
     const scene = sceneRefFromMessage(message);
     if (!scene)
         return undefined;
-    const quoteId = nonEmptyString(message.$quote_id);
     return {
         channel: 'im',
         scene,
-        ...(quoteId ? { quoteId } : {}),
     };
 }

package/lib/index.d.ts

@@ -8,8 +8,10 @@ export * from './message.js';
 export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
+export * from './system-event.js';
 export * from './side-event/index.js';
-export * from './prompt.js';
+export * from './schema-interaction.js';
+export type * from '@zhin.js/interaction';
 export * from './types.js';
 export * from './agent-prompt.js';
 export * from './utils.js';
@@ -43,6 +45,7 @@ export * from './built/login-assist.js';
 export * from './built/generated-qrcode.js';
 export * from './built/rich-segments/index.js';
 export * from './built/interactive-segments/index.js';
+export * from './built/user-interaction.js';
 export * from './built/ai-outbound/index.js';
 export { loadHtmlRenderer, seedHtmlRenderer, HTML_RENDERER_PACKAGE } from './built/html-renderer-loader.js';
 export { loadSpeechPipeline, seedSpeechPipeline, SPEECH_PACKAGE } from './built/speech-loader.js';
@@ -69,8 +72,6 @@ export * from './built/introspection-format.js';
 export * from './built/management-command-guard.js';
 export * from './built/html-to-text.js';
 export * from './built/html-segment-fallback.js';
-export * from './built/prepend-quote-context.js';
-export * from './message-quote.js';
 export * from '@zhin.js/database';
 export * from '@zhin.js/logger';
 export { Schema } from '@zhin.js/schema';

package/lib/index.js

@@ -9,8 +9,9 @@ export * from './message.js';
 export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
+export * from './system-event.js';
 export * from './side-event/index.js';
-export * from './prompt.js';
+export * from './schema-interaction.js';
 export * from './types.js';
 export * from './agent-prompt.js';
 export * from './utils.js';
@@ -44,6 +45,7 @@ export * from './built/login-assist.js';
 export * from './built/generated-qrcode.js';
 export * from './built/rich-segments/index.js';
 export * from './built/interactive-segments/index.js';
+export * from './built/user-interaction.js';
 export * from './built/ai-outbound/index.js';
 export { loadHtmlRenderer, seedHtmlRenderer, HTML_RENDERER_PACKAGE } from './built/html-renderer-loader.js';
 export { loadSpeechPipeline, seedSpeechPipeline, SPEECH_PACKAGE } from './built/speech-loader.js';
@@ -65,8 +67,6 @@ export * from './built/introspection-format.js';
 export * from './built/management-command-guard.js';
 export * from './built/html-to-text.js';
 export * from './built/html-segment-fallback.js';
-export * from './built/prepend-quote-context.js';
-export * from './message-quote.js';
 // ── 外部库 re-export ──────────────────────────────────────────────────
 export * from '@zhin.js/database';
 export * from '@zhin.js/logger';

package/lib/message.d.ts

@@ -44,8 +44,6 @@ export interface MessageBase {
     $channel: MessageChannel;
     $timestamp: number;
     $raw: string;
-    /** 本条消息引用的上游 message_id（平台原样字符串） */
-    $quote_id?: string;
 }
 /**
  * 完整消息类型，支持扩展
@@ -56,9 +54,6 @@ export declare namespace Message {
      * 工具方法：合并自定义字段与基础消息结构
      */
     function from<T extends object>(input: T, format: MessageBase): Message<T>;
-    function quoteIdFromContent(content: MessageElement[]): string | undefined;
-    function syncQuoteId(message: Message<any>): void;
-    function alignReplySegments(content: MessageElement[], quoteId?: string): void;
     function actionPayload(message: Message<any>): string | undefined;
     function isAction(message: Message<any>): boolean;
 }

package/lib/message.js

@@ -1,4 +1,3 @@
-import { alignReplySegments as alignReplySegmentsImpl, quoteIdFromContent as quoteIdFromContentImpl, syncQuoteId as syncQuoteIdImpl, } from "./message-quote.js";
 import { isActionMessage as isActionMessageImpl } from "./built/interactive-segments/action.js";
 export var Message;
 (function (Message) {
@@ -9,18 +8,6 @@ export var Message;
         return Object.assign({}, input, format);
     }
     Message.from = from;
-    function quoteIdFromContent(content) {
-        return quoteIdFromContentImpl(content);
-    }
-    Message.quoteIdFromContent = quoteIdFromContent;
-    function syncQuoteId(message) {
-        syncQuoteIdImpl(message);
-    }
-    Message.syncQuoteId = syncQuoteId;
-    function alignReplySegments(content, quoteId) {
-        alignReplySegmentsImpl(content, quoteId);
-    }
-    Message.alignReplySegments = alignReplySegments;
     function actionPayload(message) {
         for (const item of message.$content ?? []) {
             if (typeof item === 'string')

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

@@ -1,15 +1,20 @@
 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, type AdapterEndpointPhase } from '@zhin.js/adapter';
-import { type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
+import { type AdapterOperation, type EndpointManagement, type EndpointManagementCapability, type AdapterEndpointPhase, type EndpointContentResolveContext } from '@zhin.js/adapter';
+import { type ConversationEventStore, type ConversationContextBlock, type ConversationReference, type ConversationResolution, type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
 import { Message, type ConversationAddress, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type MessageSenderRef, type SendRequest } from './contracts.js';
-import type { CommandPrompt } from '@zhin.js/command';
+import { LoginAssist } from '../../built/login-assist.js';
+import type { Notice } from '../../notice.js';
+import type { Request } from '../../request.js';
+import type { SystemEvent } from '../../system-event.js';
+import type { UserInteraction } from '@zhin.js/interaction';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { type RuntimeInteractiveHandler } from './interactive.js';
 export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
-/** Generation-owned terminal route after interactive/command routing misses. */
+/** Generation-owned ingress hooks before ordinary dispatch and after it misses. */
 export interface IngressRoute {
-    route(message: Message, lease: SnapshotLease, requester: PluginId): Promise<boolean>;
+    preRoute?(message: Message, lease: SnapshotLease, requester: PluginId, conversationSequence: number | undefined): Promise<boolean>;
+    route(message: Message, lease: SnapshotLease, requester: PluginId, conversationSequence: number | undefined): Promise<boolean>;
 }
 export declare const ingressRouteToken: import("@zhin.js/plugin-runtime").Token<IngressRoute>;
 /** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
@@ -33,6 +38,7 @@ export interface ImRuntimeOptions {
      */
     readonly commandPrefix?: string;
     readonly renderer?: OutboundRenderer;
+    readonly conversationEvents?: ConversationEventStore;
     /** Process-root ingress claim (pending interaction, authentication challenge, etc.). */
     readonly inboundClaim?: (message: Message) => boolean | Promise<boolean>;
     /**
@@ -45,10 +51,20 @@ export interface ImRuntimeOptions {
 }
 export declare class ImRuntime implements MessageGateway {
     #private;
+    conversationEvents: ConversationEventStore;
     constructor(options?: ImRuntimeOptions);
+    /** Process composition replaces the bootstrap memory store after required DB activation. */
+    replaceConversationEventStore(store: ConversationEventStore): void;
+    resolveConversationReference(lease: SnapshotLease, reference: ConversationReference, context: EndpointContentResolveContext): Promise<ConversationResolution>;
+    readConversationContext(conversation: ConversationRef, consumer: string, throughSequence: number, limit?: number, excludeMessageId?: string): Promise<Readonly<{
+        blocks: readonly ConversationContextBlock[];
+        cursor: number;
+    }>>;
+    commitConversationContext(conversation: ConversationRef, consumer: string, cursor: number): Promise<void>;
     attach(snapshots: SnapshotReader): void;
     readonly permissionHost: import("@zhin.js/permission").PermissionHost;
     readonly messageBus: MessageBus;
+    readonly loginAssist: LoginAssist;
     install(resources: Scope): void;
     [generationAdmissionBinder](gate: GenerationAdmissionGate): MessageGateway;
     /**
@@ -57,12 +73,12 @@ export declare class ImRuntime implements MessageGateway {
      */
     registerInteractiveHandler(prefix: string, handler: RuntimeInteractiveHandler): () => void;
     /**
-     * Bound Prompt for this conversation.
+     * User interaction bound to this conversation.
      * `bind.subjectId` waits for that user (e.g. master) instead of the message sender.
      */
-    createPrompt(message: Message, bind?: {
+    createInteraction(message: Message, bind?: {
         readonly subjectId: string;
-    }): CommandPrompt | undefined;
+    }): UserInteraction | undefined;
     /**
      * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
      * 返回注销函数。listener 抛错不会阻断消息链路。
@@ -70,14 +86,19 @@ export declare class ImRuntime implements MessageGateway {
     onMessage(listener: (event: RuntimeMessageEvent) => void): () => void;
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
     send(request: SendRequest): Promise<DeliveryReceipt>;
+    receiveNotice(notice: Notice): Promise<void>;
+    receiveRequest(request: Request): Promise<void>;
+    receiveSystem(event: SystemEvent): Promise<void>;
     /** Console `endpoint.list` — empty until Adapter Feature projection is ready. */
     listEndpoints(): readonly {
+        readonly id: string;
         readonly name: string;
         readonly adapter: string;
         readonly owner: string;
         readonly connected: boolean;
         readonly status: 'online' | 'offline';
         readonly phase: AdapterEndpointPhase;
+        readonly operations: readonly AdapterOperation[];
         readonly managementCapabilities: readonly EndpointManagementCapability[];
     }[];
     /**
@@ -97,6 +118,7 @@ export declare class ImRuntime implements MessageGateway {
         readonly connected: boolean;
         readonly status: 'online' | 'offline';
         readonly phase: AdapterEndpointPhase;
+        readonly operations: readonly AdapterOperation[];
         readonly managementCapabilities: readonly EndpointManagementCapability[];
     } | null;
     sendEndpointMessage(input: {