@zhin.js/core 1.1.34 → 1.1.35

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

@@ -0,0 +1,191 @@
+import type { PluginId } from '@zhin.js/plugin-runtime';
+import type { ConversationRef, DeliveryReceipt, MessageRef } from '@zhin.js/im-contract';
+import type { MediaRef, Segment } from '../../built/segment-contract/types.js';
+export type { MediaRef, Segment };
+declare const componentCallBrand: "zhin.component-call/1";
+declare const rawContentBrand: "zhin.raw-content/1";
+export interface ComponentCall<TProps = unknown> {
+    readonly $content: typeof componentCallBrand;
+    readonly name: string;
+    readonly props: TProps;
+}
+export interface RawContent<TPayload = unknown> {
+    readonly $content: typeof rawContentBrand;
+    readonly payload: TPayload;
+}
+/**
+ * 出站内容：纯文本 / canonical Segment（一等公民，媒体与富文本的统一表达）/
+ * ComponentCall / RawContent，可任意嵌套数组。
+ */
+export type SendContent = string | Segment | ComponentCall | RawContent | readonly SendContent[];
+export declare function component<TProps>(name: string, props: TProps): ComponentCall<TProps>;
+export declare function raw<TPayload>(payload: TPayload): RawContent<TPayload>;
+export declare function isComponentCall(value: SendContent): value is ComponentCall;
+export declare function isRawContent(value: SendContent): value is RawContent;
+/** canonical Segment 一等公民判定（与 ComponentCall/RawContent 的 $content brand 互斥）。 */
+export declare function isSegmentContent(value: unknown): value is Segment;
+export interface MessageSenderRef {
+    readonly id: string;
+    readonly name?: string;
+    readonly roles?: readonly string[];
+}
+export interface IncomingMessage {
+    readonly conversation: ConversationRef;
+    readonly message?: MessageRef;
+    readonly content: string;
+    readonly segments?: readonly Segment[];
+    readonly sender?: MessageSenderRef;
+    /** Endpoint 实例名（如 ICQQ uin、sandbox bot name），区别于 conversation.endpoint.id（CapabilityId）。 */
+    readonly endpointId?: string;
+    /** 消息是否 @了机器人。 */
+    readonly mentioned?: boolean;
+    /** 引用/回复的原始消息。 */
+    readonly replyTo?: {
+        readonly id: string;
+    };
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 入站消息上下文快照 — 由 reply 闭包捕获，沿出站链路传递到模板编译。
+ * 定时任务 / 跨通道发送时整个 incoming 为 undefined。
+ */
+export interface IncomingContext {
+    readonly sender?: MessageSenderRef;
+    /** 收到的消息纯文本内容。 */
+    readonly content: string;
+    /** 结构化消息段（图片、@、引用等）。 */
+    readonly segments?: readonly Segment[];
+    /** 平台原生消息 ID。 */
+    readonly messageId?: string;
+    /** 消息到达时间戳（ms）。 */
+    readonly timestamp: number;
+    /** Endpoint 实例名（如 ICQQ uin、sandbox bot name）。 */
+    readonly endpointId?: string;
+    /** 消息是否 @了机器人。 */
+    readonly mentioned?: boolean;
+}
+export interface SendRequest {
+    readonly conversation: ConversationRef;
+    readonly requester: PluginId;
+    readonly content: SendContent;
+    /** Incoming message context (absent for scheduled / cross-channel sends). */
+    readonly incoming?: IncomingContext;
+}
+/**
+ * Host 侧未锚定 endpoint 的会话地址（Console RPC / OutboundHost 入参）；
+ * ImRuntime 解析 adapter/endpointKey 后锚定为完整 ConversationRef。
+ */
+export type ConversationAddress = Omit<ConversationRef, 'endpoint'>;
+export interface OutboundEnvelope {
+    readonly conversation: ConversationRef;
+    readonly requester: PluginId;
+    readonly generation: number;
+    readonly payload: unknown;
+    /** Native platform Client for the Endpoint selected by `conversation`. */
+    readonly $client: unknown;
+    /** Literal adapter name used to validate adapter-bound middleware. */
+    readonly clientAdapter?: string;
+    replace(payload: unknown): void;
+}
+/** @public Stable IM gateway contract resolved through `outboundMessageToken`. */
+export interface OutboundMessageService {
+    send(request: SendRequest): Promise<DeliveryReceipt>;
+    /**
+     * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
+     * 平台 callback 的 action 段、'text' 端点的数字回跳与指令预填直出
+     * payload 都会路由到这里。
+     */
+    registerInteractiveHandler(prefix: string, handler: (message: Message) => Promise<boolean> | boolean): () => void;
+}
+export interface MessageDispatchResult {
+    readonly matched: boolean;
+    readonly command?: string;
+    readonly owner?: PluginId;
+    readonly value?: unknown;
+}
+export declare class Message {
+    #private;
+    readonly conversation: ConversationRef;
+    readonly content: string;
+    readonly generation: number;
+    readonly sender?: MessageSenderRef | undefined;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    readonly segments?: readonly Segment[] | undefined;
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
+    readonly message?: MessageRef | undefined;
+    readonly endpointId?: string | undefined;
+    readonly mentioned?: boolean | undefined;
+    readonly replyTo?: {
+        readonly id: string;
+    } | undefined;
+    readonly clientAdapter?: string | undefined;
+    /** @internal Constructed only by the generation-owned IM Runtime. */
+    constructor(conversation: ConversationRef, content: string, generation: number, reply: (content: SendContent, requester?: PluginId, targetConversation?: ConversationAddress) => Promise<DeliveryReceipt>, sender?: MessageSenderRef | undefined, metadata?: Readonly<Record<string, unknown>>, 
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    segments?: readonly Segment[] | undefined, 
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
+    message?: MessageRef | undefined, endpointId?: string | undefined, mentioned?: boolean | undefined, replyTo?: {
+        readonly id: string;
+    } | undefined, client?: () => unknown, clientAdapter?: string | undefined);
+    /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
+    get id(): string | undefined;
+    readonly $reply: (content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * Platform-native Client that received this message. The getter is
+     * generation-scoped; retaining the returned Client after dispatch is invalid.
+     */
+    get $client(): unknown;
+    readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * 向同 Endpoint 的另一个通道发送消息（通用）。
+     *
+     * ```ts
+     * await message.$sendTo({ kind: 'channel', id: 'ch-1', parent: { kind: 'channel', id: 'guild-1' } }, '频道通知');
+     * ```
+     */
+    readonly $sendTo: (conversation: ConversationAddress, content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * 私信当前消息的发送者（同 Endpoint）。
+     *
+     * @param content 消息内容
+     * @param from 会话上下文：
+     *   - `true` — 用当前群/频道作为 parent（要求当前不在私聊中）
+     *   - `{ kind, id }` — 显式指定 parent（群或子频道）
+     *   - 省略 — 直接私信
+     *
+     * ```ts
+     * await message.$replyToPrivate('直接私信');
+     * await message.$replyToPrivate('群临时私信', true);
+     * await message.$replyToPrivate('频道私信', { kind: 'channel', id: '子频道ID' });
+     * ```
+     */
+    readonly $replyToPrivate: (content: SendContent, from?: boolean | {
+        readonly kind: 'group' | 'channel';
+        readonly id: string;
+    }) => Promise<DeliveryReceipt>;
+    /**
+     * 向指定群发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToGroup('67890', '群通知');
+     * ```
+     */
+    readonly $replyToGroup: (groupId: string, content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * 向指定频道/子频道发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToChannel('channel-1', 'guild-1', '频道通知');
+     * await message.$replyToChannel('channel-1', 'guild-1', '话题回复', 'thread-1');
+     * ```
+     */
+    readonly $replyToChannel: (channelId: string, guildId: string, content: SendContent, threadId?: string) => Promise<DeliveryReceipt>;
+}
+export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | '$client' | 'replace'>, initialPayload: unknown, resolveClient?: () => unknown): OutboundEnvelope;

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

@@ -0,0 +1,169 @@
+const componentCallBrand = 'zhin.component-call/1';
+const rawContentBrand = 'zhin.raw-content/1';
+export function component(name, props) {
+    if (!name.trim())
+        throw new TypeError('Component name cannot be empty');
+    return Object.freeze({ $content: componentCallBrand, name, props });
+}
+export function raw(payload) {
+    return Object.freeze({ $content: rawContentBrand, payload });
+}
+export function isComponentCall(value) {
+    return !Array.isArray(value)
+        && typeof value === 'object'
+        && value !== null
+        && '$content' in value
+        && value.$content === componentCallBrand;
+}
+export function isRawContent(value) {
+    return !Array.isArray(value)
+        && typeof value === 'object'
+        && value !== null
+        && '$content' in value
+        && value.$content === rawContentBrand;
+}
+/** canonical Segment 一等公民判定（与 ComponentCall/RawContent 的 $content brand 互斥）。 */
+export function isSegmentContent(value) {
+    return !Array.isArray(value)
+        && typeof value === 'object'
+        && value !== null
+        && !('$content' in value)
+        && typeof value.type === 'string'
+        && typeof value.data === 'object'
+        && value.data !== null;
+}
+export class Message {
+    conversation;
+    content;
+    generation;
+    sender;
+    metadata;
+    segments;
+    message;
+    endpointId;
+    mentioned;
+    replyTo;
+    clientAdapter;
+    #resolveClient;
+    /** @internal Constructed only by the generation-owned IM Runtime. */
+    constructor(conversation, content, generation, reply, sender, metadata = Object.freeze({}), 
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    segments, 
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
+    message, endpointId, mentioned, replyTo, client = () => {
+        throw new Error('Message has no Endpoint Client context');
+    }, clientAdapter) {
+        this.conversation = conversation;
+        this.content = content;
+        this.generation = generation;
+        this.sender = sender;
+        this.metadata = metadata;
+        this.segments = segments;
+        this.message = message;
+        this.endpointId = endpointId;
+        this.mentioned = mentioned;
+        this.replyTo = replyTo;
+        this.clientAdapter = clientAdapter;
+        this.#resolveClient = client;
+        this.$reply = (content) => reply(content);
+        this.$replyFrom = (requester, content) => reply(content, requester);
+        this.$sendTo = (target, content) => reply(content, undefined, target);
+        this.$replyToPrivate = (content, from) => {
+            if (!sender)
+                throw new Error('Cannot $replyToPrivate: message has no sender');
+            let parent;
+            if (from === true) {
+                if (conversation.kind !== 'group' && conversation.kind !== 'channel') {
+                    throw new Error('Cannot $replyToPrivate with from=true: current conversation must be a group or channel');
+                }
+                parent = { kind: conversation.kind, id: conversation.id };
+            }
+            else if (from != null && typeof from === 'object') {
+                parent = from;
+            }
+            return reply(content, undefined, {
+                kind: 'private',
+                id: sender.id,
+                ...(parent ? { parent } : {}),
+            });
+        };
+        this.$replyToGroup = (groupId, content) => {
+            return reply(content, undefined, { kind: 'group', id: groupId });
+        };
+        this.$replyToChannel = (channelId, guildId, content, threadId) => {
+            return reply(content, undefined, {
+                kind: 'channel',
+                id: channelId,
+                parent: { kind: 'channel', id: guildId },
+                ...(threadId ? { threadId } : {}),
+            });
+        };
+        Object.freeze(this);
+    }
+    /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
+    get id() {
+        return this.message?.id;
+    }
+    $reply;
+    /**
+     * Platform-native Client that received this message. The getter is
+     * generation-scoped; retaining the returned Client after dispatch is invalid.
+     */
+    get $client() {
+        return this.#resolveClient();
+    }
+    $replyFrom;
+    /**
+     * 向同 Endpoint 的另一个通道发送消息（通用）。
+     *
+     * ```ts
+     * await message.$sendTo({ kind: 'channel', id: 'ch-1', parent: { kind: 'channel', id: 'guild-1' } }, '频道通知');
+     * ```
+     */
+    $sendTo;
+    /**
+     * 私信当前消息的发送者（同 Endpoint）。
+     *
+     * @param content 消息内容
+     * @param from 会话上下文：
+     *   - `true` — 用当前群/频道作为 parent（要求当前不在私聊中）
+     *   - `{ kind, id }` — 显式指定 parent（群或子频道）
+     *   - 省略 — 直接私信
+     *
+     * ```ts
+     * await message.$replyToPrivate('直接私信');
+     * await message.$replyToPrivate('群临时私信', true);
+     * await message.$replyToPrivate('频道私信', { kind: 'channel', id: '子频道ID' });
+     * ```
+     */
+    $replyToPrivate;
+    /**
+     * 向指定群发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToGroup('67890', '群通知');
+     * ```
+     */
+    $replyToGroup;
+    /**
+     * 向指定频道/子频道发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToChannel('channel-1', 'guild-1', '频道通知');
+     * await message.$replyToChannel('channel-1', 'guild-1', '话题回复', 'thread-1');
+     * ```
+     */
+    $replyToChannel;
+}
+export function createOutboundEnvelope(request, initialPayload, resolveClient = () => undefined) {
+    let payload = initialPayload;
+    return Object.freeze({
+        ...request,
+        get payload() { return payload; },
+        get $client() { return resolveClient(); },
+        replace(next) { payload = next; },
+    });
+}

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

@@ -0,0 +1,177 @@
+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 AdapterOperation, type EndpointManagement, type EndpointManagementCapability, type AdapterEndpointPhase, type EndpointContentResolveContext, type EndpointEvent, type EndpointEventGateway } from '@zhin.js/adapter';
+import { type ConversationEventStore, type ConversationContextBlock, type ConversationReference, type ConversationResolution, type ConversationRef, type DeliveryReceipt, type EndpointCapabilities, type MessageRef } from '@zhin.js/im-contract';
+import { Message, type ConversationAddress, type IncomingMessage, type OutboundMessageService, type MessageSenderRef, type SendRequest } from './contracts.js';
+import { LoginAssist } from '../../built/login-assist.js';
+import type { UserInteraction } from '@zhin.js/interaction';
+import { OutboundRenderer } from './outbound-renderer.js';
+import { type RuntimeInteractiveHandler } from './interactive.js';
+/** @public Stable inbound and outbound IM gateway token for Adapter integrations. */
+export declare const outboundMessageToken: import("@zhin.js/plugin-runtime").Token<OutboundMessageService>;
+/** Generation-owned ingress hooks before ordinary dispatch and after it misses. */
+export interface IngressRoute {
+    preRoute?(message: Message, lease: SnapshotLease, requester: PluginId, conversationSequence: number | undefined): Promise<boolean>;
+    /** A live pre-route handoff that must run before handlers and commands. */
+    shouldRouteBeforeDispatch?(message: Message): 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 仅为截断预览，不含完整原始段）。 */
+export interface RuntimeMessageEvent {
+    readonly direction: 'inbound' | 'outbound';
+    readonly conversation: ConversationRef;
+    /** inbound：发送者。 */
+    readonly sender?: MessageSenderRef;
+    /** outbound：发起方插件。 */
+    readonly requester?: PluginId;
+    /** 预览文本，截断至 200 字。 */
+    readonly contentPreview: string;
+    readonly messageId?: string;
+    readonly timestamp: number;
+}
+export declare const messagePreviewLimit = 200;
+export interface ImRuntimeOptions {
+    /**
+     * 全局静态命令前缀（如 `'/'`）。缺省时按适配器实例 config 的
+     * `commandPrefix` 解析（`endpoints[i]` 可逐项覆盖），默认 `''` 无前缀。
+     */
+    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>;
+    /**
+     * 入站 sender 增强：在构造 Message 前，将框架级角色（master / trusted）
+     * 合并到 sender.roles，使整个下游链路（命令分发、agent ingress 等）都能读到完整角色。
+     *
+     * 返回增强后的 sender（可原样返回）。缺省时 sender 保留适配器给出的平台角色。
+     */
+    readonly enrichSender?: (sender: MessageSenderRef | undefined, conversation: IncomingMessage['conversation'], snapshot: RuntimeSnapshot) => MessageSenderRef | undefined;
+}
+export declare class ImRuntime implements OutboundMessageService {
+    #private;
+    conversationEvents: ConversationEventStore;
+    constructor(options?: ImRuntimeOptions);
+    /** Process composition replaces the bootstrap memory store after required DB activation. */
+    replaceConversationEventStore(store: ConversationEventStore): void;
+    /** Pins all nested IM operations to the snapshot current at operation ingress. */
+    runWithSnapshotView<T>(operation: () => Promise<T>): Promise<T>;
+    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;
+    /** The sole Adapter ingress, also installed as endpointEventGatewayToken. */
+    readonly endpointEvents: EndpointEventGateway & {
+        [generationAdmissionBinder](gate: GenerationAdmissionGate): EndpointEventGateway;
+    };
+    [generationAdmissionBinder](gate: GenerationAdmissionGate): OutboundMessageService;
+    /**
+     * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
+     * 在 Command dispatch 之前路由：action 段 / 数字回跳 / 指令预填 payload。
+     */
+    registerInteractiveHandler(prefix: string, handler: RuntimeInteractiveHandler): () => void;
+    /**
+     * User interaction bound to this conversation.
+     * `bind.subjectId` waits for that user (e.g. master) instead of the message sender.
+     */
+    createInteraction(message: Message, bind?: {
+        readonly subjectId: string;
+    }): UserInteraction | undefined;
+    /**
+     * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
+     * 返回注销函数。listener 抛错不会阻断消息链路。
+     */
+    onMessage(listener: (event: RuntimeMessageEvent) => void): () => void;
+    send(request: SendRequest): Promise<DeliveryReceipt>;
+    /** Sends through the exact generation lease that admitted the current operation. */
+    sendWithSnapshotLease(lease: SnapshotLease, request: SendRequest): Promise<DeliveryReceipt>;
+    receiveEndpointEvent(event: EndpointEvent, admission?: GenerationAdmissionGate): Promise<unknown>;
+    /** 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[];
+    }[];
+    /** Exact operation capabilities for one concrete live Endpoint. */
+    endpointCapabilities(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+    }): EndpointCapabilities | undefined;
+    /**
+     * Console `GET /api/stats` 同源计数：非 root 插件节点 + AdapterIndex endpoints。
+     * 供命令 / 状态卡等在 Plugin Runtime 下读取（legacy `root.adapters` / `root.children` 已不存在）。
+     */
+    inventory(): Readonly<{
+        plugins: number;
+        endpoints: {
+            readonly total: number;
+            readonly online: number;
+        };
+    }>;
+    getEndpoint(adapter: string, endpointKey: string): {
+        readonly name: string;
+        readonly adapter: string;
+        readonly connected: boolean;
+        readonly status: 'online' | 'offline';
+        readonly phase: AdapterEndpointPhase;
+        readonly operations: readonly AdapterOperation[];
+        readonly managementCapabilities: readonly EndpointManagementCapability[];
+    } | null;
+    sendEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+        readonly conversation: ConversationAddress;
+        readonly content: unknown;
+    }): Promise<{
+        messageId: string;
+    }>;
+    /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
+    addEndpointReaction(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+        readonly message: MessageRef;
+        readonly emoji: string;
+        readonly sceneType?: string;
+        readonly channelId?: string;
+    }): Promise<string | null>;
+    removeEndpointReaction(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+        readonly message: MessageRef;
+        readonly reactionId: string;
+    }): Promise<void>;
+    /** Activity-feedback autoRemove: recall a previously sent status message. */
+    recallEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+        readonly message: MessageRef;
+    }): Promise<void>;
+    editEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+        readonly message: MessageRef;
+        readonly content: unknown;
+    }): Promise<string | null>;
+    setEndpointTyping(input: {
+        readonly adapter: string;
+        readonly endpointKey: string;
+        readonly conversation: ConversationRef;
+        readonly active?: boolean;
+    }): Promise<void>;
+    /** Run one management operation while the Endpoint generation stays leased. */
+    withEndpointManagement<T>(adapter: string, endpointKey: string, run: (management: EndpointManagement) => T | Promise<T>): Promise<T | null>;
+}