@zhin.js/core 1.3.4 → 1.4.0

package/README.md

@@ -1,5 +1,17 @@
 # @zhin.js/core
 
+## Plugin Runtime 子路径
+
+新的 owner-aware IM 能力已经并入 Core，作为 Plugin Runtime 的正式领域接口：
+
+- `@zhin.js/core/runtime`
+
+`@zhin.js/adapter`、`@zhin.js/command`、`@zhin.js/component` 与
+`@zhin.js/middleware` 提供纯 definition、约定发现 provider 和 generation projection；
+Core Runtime 只消费它们发布的 snapshot。
+旧根入口的 `addCommand`、`addComponent`、`addMiddleware` 暂时作为作者兼容接口保留，后续
+只向 RuntimeSnapshot 投影，不再维护第二套运行时权威。
+
 Zhin.js **IM/多通道运行时**包：Plugin、Adapter、**Endpoint**、MessageDispatcher 与统一出站链。**AI 编排（ZhinAgent、工具安全、MCP）在 [`@zhin.js/agent`](../agent/README.md)**；本包仅 selective re-export `@zhin.js/ai` 的 Provider / Agent 原语供插件直接使用。
 
 领域词汇见 [CONTEXT.md](./CONTEXT.md)；入站/出站流程见 [消息如何流转](../../docs/essentials/message-flow.md)。

package/lib/adapter.js

@@ -77,7 +77,11 @@ export class Adapter extends EventEmitter {
             logger: this.logger,
             getMaxConcurrentMessages: () => this.maxConcurrentMessages,
             getPendingMessages: () => this.#pendingMessages,
-            decrementPending: () => { this.#pendingMessages--; },
+            decrementPending: () => {
+                // stop() may zero the counter while in-flight receives still finish;
+                // never let the budget go negative.
+                this.#pendingMessages = Math.max(0, this.#pendingMessages - 1);
+            },
         });
     }
     /** 入站消息管线（替代 emit override 的隐式管线） */
@@ -291,6 +295,9 @@ export class Adapter extends EventEmitter {
         }
         // 无论是否有错误，始终完成清理
         this.endpoints.clear();
+        // Drop in-flight concurrency counter so a subsequent start() does not
+        // inherit a stale backpressure budget from the previous generation.
+        this.#pendingMessages = 0;
         // 从 adapters 数组中移除（可能因重复 start 出现多条同名，需全部删掉）
         const rootAdapters = this.plugin.root.adapters;
         for (let i = rootAdapters.length - 1; i >= 0; i--) {

package/lib/built/authorization.js

@@ -1,6 +1,6 @@
 import { mergeAITriggerConfig, resolveSenderRoles, } from './ai-trigger.js';
-import { formatCompact, Logger } from '@zhin.js/logger';
-const logger = new Logger(null, 'Authorization');
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('Authorization');
 function findEndpointEntryFromConfig(config, adapter, endpointId) {
     const endpoints = config.endpoints;
     if (!Array.isArray(endpoints))

package/lib/built/login-assist.d.ts

@@ -7,9 +7,12 @@
  *
  * 事件：
  *   endpoint.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.expired — 超时自动取消时触发，payload: PendingLoginTask
  */
 import type { Plugin } from '../plugin.js';
 export type LoginAssistType = 'qrcode' | 'sms' | 'slider' | 'device' | 'auth' | 'other';
+/** 默认 5 分钟；扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
+export declare const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS: number;
 export interface PendingLoginTaskPayload {
     /** 说明文案（如「请扫码登录」） */
     message?: string;
@@ -27,16 +30,30 @@ export interface PendingLoginTask {
     type: LoginAssistType;
     payload: PendingLoginTaskPayload;
     createdAt: number;
+    /** 到期时间戳（ms）；无超时则为 undefined */
+    expiresAt?: number;
+}
+export interface WaitForInputOptions {
+    /**
+     * 超时毫秒。默认 {@link DEFAULT_LOGIN_ASSIST_TIMEOUT_MS}。
+     * 传 `0` / `Infinity` / 负数表示不超时（仅测试或显式长驻场景）。
+     */
+    timeoutMs?: number;
 }
 export declare class LoginAssist {
     private readonly plugin;
     private readonly pending;
     private idSeq;
-    constructor(plugin: Plugin);
+    /** 构造时默认超时；可被 waitForInput options 覆盖 */
+    private readonly defaultTimeoutMs;
+    constructor(plugin: Plugin, options?: {
+        defaultTimeoutMs?: number;
+    });
     /**
      * 生产者：等待用户输入后 resolve。会发出 endpoint.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * 超时后 reject 并 emit `endpoint.login.expired`。
      */
-    waitForInput(adapter: string, endpointId: string, type: LoginAssistType, payload?: PendingLoginTaskPayload): Promise<string | Record<string, unknown>>;
+    waitForInput(adapter: string, endpointId: string, type: LoginAssistType, payload?: PendingLoginTaskPayload, options?: WaitForInputOptions): Promise<string | Record<string, unknown>>;
     /**
      * 消费者：提交结果，对应 waitForInput 的 Promise 会 resolve。
      */

package/lib/built/login-assist.js

@@ -7,7 +7,10 @@
  *
  * 事件：
  *   endpoint.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.expired — 超时自动取消时触发，payload: PendingLoginTask
  */
+/** 默认 5 分钟；扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
+export const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS = 5 * 60 * 1000;
 // ============================================================================
 // LoginAssist 服务
 // ============================================================================
@@ -15,24 +18,48 @@ export class LoginAssist {
     plugin;
     pending = new Map();
     idSeq = 0;
-    constructor(plugin) {
+    /** 构造时默认超时；可被 waitForInput options 覆盖 */
+    defaultTimeoutMs;
+    constructor(plugin, options) {
         this.plugin = plugin;
+        this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_LOGIN_ASSIST_TIMEOUT_MS;
     }
     /**
      * 生产者：等待用户输入后 resolve。会发出 endpoint.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * 超时后 reject 并 emit `endpoint.login.expired`。
      */
-    waitForInput(adapter, endpointId, type, payload = {}) {
+    waitForInput(adapter, endpointId, type, payload = {}, options) {
         const id = `login-${Date.now()}-${++this.idSeq}`;
+        const timeoutMs = resolveTimeoutMs(options?.timeoutMs, this.defaultTimeoutMs);
+        const createdAt = Date.now();
         const task = {
             id,
             adapter,
             endpointId,
             type,
             payload: { message: payload.message ?? '', ...payload },
-            createdAt: Date.now(),
+            createdAt,
+            ...(timeoutMs != null ? { expiresAt: createdAt + timeoutMs } : {}),
         };
         const promise = new Promise((resolve, reject) => {
-            this.pending.set(id, { task, resolve, reject });
+            const entry = { task, resolve, reject };
+            if (timeoutMs != null) {
+                entry.timer = setTimeout(() => {
+                    if (!this.pending.has(id))
+                        return;
+                    this.pending.delete(id);
+                    try {
+                        this.plugin.emit('endpoint.login.expired', task);
+                    }
+                    catch {
+                        /* observer failure must not leave the producer hanging forever */
+                    }
+                    reject(new Error(`LoginAssist task timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                // Node: 不阻止进程退出
+                entry.timer.unref?.();
+            }
+            this.pending.set(id, entry);
             this.plugin.emit('endpoint.login.pending', task);
         });
         return promise;
@@ -45,6 +72,8 @@ export class LoginAssist {
         if (!entry)
             return false;
         this.pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
         entry.resolve(value);
         return true;
     }
@@ -56,6 +85,8 @@ export class LoginAssist {
         if (!entry)
             return false;
         this.pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
         entry.reject(new Error(reason));
         return true;
     }
@@ -67,8 +98,16 @@ export class LoginAssist {
     }
     dispose() {
         for (const [, entry] of this.pending) {
+            if (entry.timer)
+                clearTimeout(entry.timer);
             entry.reject(new Error('LoginAssist disposed'));
         }
         this.pending.clear();
     }
 }
+function resolveTimeoutMs(explicit, fallback) {
+    const raw = explicit === undefined ? fallback : explicit;
+    if (!Number.isFinite(raw) || raw <= 0)
+        return undefined;
+    return raw;
+}

package/lib/built/platform-permit.js

@@ -1,18 +1,25 @@
 import { parsePlatformPermitName, isPlatformPermit } from './permit-parse.js';
 const checkers = new Map();
-const registeredDefaultSceneCheckers = new Set();
+const defaultSceneRegistrations = new Map();
 export function registerPlatformPermitChecker(adapter, checker) {
     const key = String(adapter);
-    checkers.set(key, checker);
+    const registrations = checkers.get(key) ?? [];
+    registrations.push(checker);
+    checkers.set(key, registrations);
     return () => {
-        if (checkers.get(key) === checker) {
+        const current = checkers.get(key);
+        if (!current)
+            return;
+        const index = current.lastIndexOf(checker);
+        if (index >= 0)
+            current.splice(index, 1);
+        if (current.length === 0)
             checkers.delete(key);
-        }
     };
 }
 export function clearPlatformPermitCheckers() {
     checkers.clear();
-    registeredDefaultSceneCheckers.clear();
+    defaultSceneRegistrations.clear();
 }
 export function checkPlatformPermit(name, message) {
     const parsed = parsePlatformPermitName(name);
@@ -20,7 +27,8 @@ export function checkPlatformPermit(name, message) {
         return false;
     if (String(message.$adapter) !== parsed.adapter)
         return false;
-    const checker = checkers.get(parsed.adapter);
+    const registrations = checkers.get(parsed.adapter);
+    const checker = registrations?.[registrations.length - 1];
     if (!checker)
         return false;
     return checker(parsed.perm, message);
@@ -58,9 +66,26 @@ export function createSceneRolePlatformChecker() {
 /** 为适配器注册默认场景治理 platform checker（幂等） */
 export function registerDefaultScenePlatformPermitChecker(adapter) {
     const key = String(adapter);
-    if (registeredDefaultSceneCheckers.has(key)) {
-        return () => { };
+    const existing = defaultSceneRegistrations.get(key);
+    if (existing) {
+        existing.references += 1;
+        return () => releaseDefaultSceneChecker(key, existing);
     }
-    registeredDefaultSceneCheckers.add(key);
-    return registerPlatformPermitChecker(key, createSceneRolePlatformChecker());
+    const checker = createSceneRolePlatformChecker();
+    const registration = {
+        checker,
+        dispose: registerPlatformPermitChecker(key, checker),
+        references: 1,
+    };
+    defaultSceneRegistrations.set(key, registration);
+    return () => releaseDefaultSceneChecker(key, registration);
+}
+function releaseDefaultSceneChecker(key, registration) {
+    if (defaultSceneRegistrations.get(key) !== registration)
+        return;
+    registration.references -= 1;
+    if (registration.references > 0)
+        return;
+    defaultSceneRegistrations.delete(key);
+    registration.dispose();
 }

package/lib/built/segment-contract/index.d.ts

@@ -1,6 +1,7 @@
 export type { Segment, SegmentBase, MediaRef, TextSegment, MentionSegment, ImageSegment, ReplySegment, ForwardSegment, FaceSegment, DiceSegment, RpsSegment, } from './types.js';
 export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
 export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
 export { segmentsForImDelivery } from './delivery.js';
 export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
 export { createImageSegment } from './image.js';

package/lib/built/segment-contract/index.js

@@ -1,5 +1,6 @@
 export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
 export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
 export { segmentsForImDelivery } from './delivery.js';
 export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
 export { createImageSegment } from './image.js';

package/lib/built/segment-contract/json-schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Canonical outbound segment 的 JSON Schema SSOT —— 供 AI structured output
+ * （AI SDK `Output.object({ schema })`）约束模型直接输出 zhin 消息段数组。
+ *
+ * 与 validate.ts（@zhin.js/schema 运行时校验）表达同一组约束的 JSON Schema 形态；
+ * 严格段类型集合必须与 assert.ts 的 STRICT_CANONICAL_TYPES 保持一致
+ * （tests/segment-contract/json-schema.test.ts 有交叉防漂移测试）。
+ *
+ * 注意：解析侧 parseOutboundSegment 对严格段要求 canonical 形态
+ * （如 image 必须携带 data.media: MediaRef），本 schema 与之对齐。
+ */
+type JsonSchemaObject = Record<string, unknown>;
+/** MediaRef（canonical 媒体引用）：types.ts 的 MediaRef 接口 */
+export declare const mediaRefJsonSchema: JsonSchemaObject;
+/** 严格段类型集合（SSOT：assert.ts STRICT_CANONICAL_TYPES） */
+export declare const STRICT_OUTBOUND_SEGMENT_TYPES: readonly ["text", "mention", "image", "reply", "forward", "face", "dice", "rps"];
+/**
+ * 单条 outbound 消息段的 JSON Schema。
+ * 严格段镜像 validate.ts 的 data 约束；宽松段走 generic 分支。
+ */
+export declare const outboundSegmentJsonSchema: JsonSchemaObject;
+/**
+ * AI 结构化出站根对象（ADR 0025 JSON DSL 的 schema 形态）。
+ * 与 parseAiOutboundJson / ZhinAiOutboundPayload 对齐：text、mentions、segments
+ * 均为可选（provider strict 模式兼容性考虑），"至少一项"由 prompt 与下游校验兜底。
+ */
+export declare const aiOutboundJsonSchema: JsonSchemaObject;
+export {};

package/lib/built/segment-contract/json-schema.js

@@ -0,0 +1,128 @@
+/**
+ * Canonical outbound segment 的 JSON Schema SSOT —— 供 AI structured output
+ * （AI SDK `Output.object({ schema })`）约束模型直接输出 zhin 消息段数组。
+ *
+ * 与 validate.ts（@zhin.js/schema 运行时校验）表达同一组约束的 JSON Schema 形态；
+ * 严格段类型集合必须与 assert.ts 的 STRICT_CANONICAL_TYPES 保持一致
+ * （tests/segment-contract/json-schema.test.ts 有交叉防漂移测试）。
+ *
+ * 注意：解析侧 parseOutboundSegment 对严格段要求 canonical 形态
+ * （如 image 必须携带 data.media: MediaRef），本 schema 与之对齐。
+ */
+const platformJsonSchema = {
+    type: 'object',
+    additionalProperties: true,
+    description: '平台专有字段（一般无需输出）',
+};
+/** MediaRef（canonical 媒体引用）：types.ts 的 MediaRef 接口 */
+export const mediaRefJsonSchema = {
+    type: 'object',
+    properties: {
+        kind: {
+            type: 'string',
+            enum: ['url', 'path', 'base64'],
+            description: 'url=http(s) 链接；path=本地文件路径；base64=内联 base64 数据',
+        },
+        value: { type: 'string', description: '媒体内容：URL / 文件路径 / 纯 base64' },
+        mime_type: { type: 'string', description: '如 image/png、audio/mpeg' },
+    },
+    required: ['kind', 'value'],
+    additionalProperties: false,
+};
+function strictBranch(type, data) {
+    return {
+        type: 'object',
+        properties: {
+            type: { const: type },
+            data,
+            platform: platformJsonSchema,
+        },
+        required: ['type', 'data'],
+        additionalProperties: false,
+    };
+}
+function dataObject(properties, required) {
+    return { type: 'object', properties, required: [...required], additionalProperties: false };
+}
+/** 宽松分支：未纳入严格契约的段类型，仅约束顶层形状（与 isCanonicalSegment 宽松路径一致） */
+const looseBranch = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            enum: ['video', 'audio', 'voice', 'record', 'file', 'link', 'markdown', 'html', 'keyboard', 'action'],
+        },
+        data: { type: 'object' },
+        platform: platformJsonSchema,
+    },
+    required: ['type', 'data'],
+    additionalProperties: false,
+};
+/** 严格段类型集合（SSOT：assert.ts STRICT_CANONICAL_TYPES） */
+export const STRICT_OUTBOUND_SEGMENT_TYPES = [
+    'text', 'mention', 'image', 'reply', 'forward', 'face', 'dice', 'rps',
+];
+/**
+ * 单条 outbound 消息段的 JSON Schema。
+ * 严格段镜像 validate.ts 的 data 约束；宽松段走 generic 分支。
+ */
+export const outboundSegmentJsonSchema = {
+    description: 'zhin 消息段 {type, data, platform?}',
+    anyOf: [
+        strictBranch('text', dataObject({
+            text: { type: 'string', description: '文本内容' },
+        }, ['text'])),
+        strictBranch('mention', dataObject({
+            target: { type: 'string', description: '被 @ 用户的平台 id' },
+            name: { type: 'string' },
+        }, ['target'])),
+        strictBranch('image', dataObject({
+            media: mediaRefJsonSchema,
+            alt: { type: 'string' },
+        }, ['media'])),
+        strictBranch('reply', dataObject({
+            message_id: { type: 'string', description: '被引用消息的平台消息 id' },
+        }, ['message_id'])),
+        strictBranch('forward', dataObject({
+            forward_id: { type: 'string' },
+            title: { type: 'string' },
+            messages: { type: 'array', items: { type: 'array' } },
+        }, ['forward_id'])),
+        strictBranch('face', dataObject({
+            id: { anyOf: [{ type: 'string' }, { type: 'number' }], description: '平台表情 id' },
+            name: { type: 'string' },
+        }, ['id'])),
+        strictBranch('dice', dataObject({
+            result: { type: 'number' },
+        }, [])),
+        strictBranch('rps', dataObject({
+            result: { type: 'number' },
+        }, [])),
+        looseBranch,
+    ],
+};
+/**
+ * AI 结构化出站根对象（ADR 0025 JSON DSL 的 schema 形态）。
+ * 与 parseAiOutboundJson / ZhinAiOutboundPayload 对齐：text、mentions、segments
+ * 均为可选（provider strict 模式兼容性考虑），"至少一项"由 prompt 与下游校验兜底。
+ */
+export const aiOutboundJsonSchema = {
+    type: 'object',
+    properties: {
+        text: {
+            type: 'string',
+            description: '纯文本回复正文；与 segments 至少输出一项。使用 mentions 时必填',
+        },
+        mentions: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '要 @ 的会话成员引用（昵称或 id，由宿主解析为平台账号）；需配合 text 使用',
+        },
+        segments: {
+            type: 'array',
+            items: outboundSegmentJsonSchema,
+            description: 'zhin 消息段数组，如 [{type:"image",data:{media:{kind:"url",value:"https://…"}}},{type:"text",data:{text:"…"}}]',
+        },
+    },
+    additionalProperties: false,
+};

package/lib/endpoint.d.ts

@@ -1,12 +1,15 @@
 import type { Adapters, Adapter } from './adapter.js';
 import type { EndpointCapabilitiesConfig, FullEndpoint } from './endpoint-capabilities.js';
+import type { EndpointWithManagement } from '@zhin.js/adapter';
+export type { EndpointChannel, EndpointChannelParent, EndpointFriend, EndpointGroup, EndpointManagement, EndpointWithManagement, EndpointManagementCapability, } from '@zhin.js/adapter';
+export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
 export type { EndpointCapability, EndpointCapabilitiesConfig, InboundEndpoint, OutboundEndpoint, FullEndpoint, CapableEndpoint, } from './endpoint-capabilities.js';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';
 /**
  * Endpoint 接口：全双工平台机器人（入站 + 出站）。
  * 纯入站 / 纯出站请实现 InboundEndpoint / OutboundEndpoint。
  */
-export type Endpoint<Config extends object = object, Event extends object = object> = FullEndpoint<Config, Event>;
+export type Endpoint<Config extends object = object, Event extends object = object> = FullEndpoint<Config, Event> & EndpointWithManagement;
 export declare namespace Endpoint {
     type Config<K extends keyof Adapters = keyof Adapters> = Adapter.EndpointConfig<Adapter.InferEndpoint<Adapters[K]>> & EndpointCapabilitiesConfig & {
         context: K;

package/lib/endpoint.js

@@ -1 +1,2 @@
+export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';

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

@@ -0,0 +1,71 @@
+import type { CapabilityId, PluginId } from '@zhin.js/plugin-runtime';
+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;
+}
+export type SendContent = string | 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;
+export interface IncomingMessage {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly content: string;
+    readonly id?: string;
+    readonly sender?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface SendRequest {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly requester: PluginId;
+    readonly content: SendContent;
+    readonly parent?: ChannelParent;
+}
+/** Console 通道的来源场景（群临时会话 parent.group / QQ 子频道 parent.guild）。 */
+export interface ChannelParent {
+    readonly type?: string;
+    readonly id?: string;
+    readonly name?: string;
+}
+export interface OutboundEnvelope {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly requester: PluginId;
+    readonly generation: number;
+    readonly payload: unknown;
+    readonly parent?: ChannelParent;
+    replace(payload: unknown): void;
+}
+export interface MessageGateway {
+    receive(input: IncomingMessage): Promise<MessageDispatchResult>;
+    send(request: SendRequest): Promise<unknown>;
+}
+export interface MessageDispatchResult {
+    readonly matched: boolean;
+    readonly command?: string;
+    readonly owner?: PluginId;
+    readonly value?: unknown;
+}
+export declare class Message {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly content: string;
+    readonly generation: number;
+    readonly id?: string | undefined;
+    readonly sender?: string | undefined;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    constructor(adapter: CapabilityId, target: string, content: string, generation: number, reply: (content: SendContent, requester?: PluginId) => Promise<unknown>, id?: string | undefined, sender?: string | undefined, metadata?: Readonly<Record<string, unknown>>);
+    readonly $reply: (content: SendContent) => Promise<unknown>;
+    readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<unknown>;
+}
+export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;
+export {};

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

@@ -0,0 +1,55 @@
+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;
+}
+export class Message {
+    adapter;
+    target;
+    content;
+    generation;
+    id;
+    sender;
+    metadata;
+    constructor(adapter, target, content, generation, reply, id, sender, metadata = Object.freeze({})) {
+        this.adapter = adapter;
+        this.target = target;
+        this.content = content;
+        this.generation = generation;
+        this.id = id;
+        this.sender = sender;
+        this.metadata = metadata;
+        this.$reply = (content) => reply(content);
+        this.$replyFrom = (requester, content) => reply(content, requester);
+        Object.freeze(this);
+    }
+    $reply;
+    $replyFrom;
+}
+export function createOutboundEnvelope(request, initialPayload) {
+    let payload = initialPayload;
+    return Object.freeze({
+        ...request,
+        get payload() { return payload; },
+        replace(next) { payload = next; },
+    });
+}