@zhin.js/core 1.3.4 → 1.4.0

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

@@ -0,0 +1,109 @@
+import { Scope, type CapabilityId, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { type EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
+import { Message, type ChannelParent, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type SendRequest } from './contracts.js';
+import { OutboundRenderer } from './outbound-renderer.js';
+export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
+/** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
+export interface RuntimeMessageEvent {
+    readonly direction: 'inbound' | 'outbound';
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    /** inbound：发送者 id。 */
+    readonly sender?: string;
+    /** outbound：发起方插件。 */
+    readonly requester?: PluginId;
+    /** inbound：从 target 前缀解析的场景（`group:xx` → `group`）。 */
+    readonly channelType?: string;
+    /** 预览文本，截断至 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;
+}
+export declare class ImRuntime implements MessageGateway {
+    #private;
+    constructor(options?: ImRuntimeOptions);
+    attach(snapshots: SnapshotStore): void;
+    /**
+     * Optional Host AI / fallback path after Command miss (or non-prefixed text).
+     * Return true when the message was handled (reply already sent).
+     * `requester` is the Adapter Endpoint owner (for CapabilityIngress inheritance).
+     */
+    setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
+    install(resources: Scope): void;
+    /**
+     * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
+     * 返回注销函数。listener 抛错不会阻断消息链路。
+     */
+    onMessage(listener: (event: RuntimeMessageEvent) => void): () => void;
+    receive(input: IncomingMessage): Promise<MessageDispatchResult>;
+    send(request: SendRequest): Promise<unknown>;
+    /** Console `endpoint.list` — empty until Adapter Feature projection is ready. */
+    listEndpoints(): readonly {
+        readonly name: string;
+        readonly adapter: string;
+        readonly owner: string;
+        readonly connected: boolean;
+        readonly status: 'online' | 'offline';
+        readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+        readonly managementCapabilities: readonly EndpointManagementCapability[];
+    }[];
+    getEndpoint(adapter: string, endpointId: string): {
+        readonly name: string;
+        readonly adapter: string;
+        readonly connected: boolean;
+        readonly status: 'online' | 'offline';
+        readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+        readonly managementCapabilities: readonly EndpointManagementCapability[];
+    } | null;
+    sendEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly channelId: string;
+        readonly channelType: string;
+        readonly content: unknown;
+        readonly parent?: ChannelParent;
+    }): Promise<{
+        messageId: string;
+    }>;
+    /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
+    addEndpointReaction(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly messageId: string;
+        readonly emoji: string;
+        readonly sceneType?: string;
+        readonly channelId?: string;
+    }): Promise<string | null>;
+    removeEndpointReaction(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly messageId: string;
+        readonly reactionId: string;
+    }): Promise<void>;
+    /** Activity-feedback autoRemove: recall a previously sent status message. */
+    recallEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly messageId: string;
+    }): Promise<void>;
+    /**
+     * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
+     * @deprecated Host callers should use `getEndpointManagement()`.
+     */
+    getLiveEndpoint(adapter: string, endpointId: string): unknown | null;
+    /**
+     * Narrow Host seam for Console social/group management. An empty object means
+     * the Endpoint exists but implements no management operations; null means it
+     * cannot be resolved.
+     */
+    getEndpointManagement(adapter: string, endpointId: string): EndpointManagement | null;
+}

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

@@ -0,0 +1,399 @@
+import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
+import { adapterFeatureId, isAdapterIndex, resolveEndpointManagement, } from '@zhin.js/adapter';
+import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
+import { Message, createOutboundEnvelope, } from './contracts.js';
+import { defaultCommandPrefixResolver, MessageDispatcher } from './message-dispatcher.js';
+import { OutboundRenderer } from './outbound-renderer.js';
+import { normalizeOutboundPayload } from './outbound-segments.js';
+export const messageGatewayToken = createToken('zhin.im.message-gateway');
+export const messagePreviewLimit = 200;
+export class ImRuntime {
+    #dispatcher;
+    #renderer;
+    #messageListeners = new Set();
+    #snapshots;
+    #unmatchedHandler;
+    constructor(options = {}) {
+        this.#dispatcher = new MessageDispatcher(options.commandPrefix === undefined
+            ? defaultCommandPrefixResolver
+            : () => options.commandPrefix ?? '');
+        this.#renderer = options.renderer ?? new OutboundRenderer();
+    }
+    attach(snapshots) {
+        if (this.#snapshots && this.#snapshots !== snapshots) {
+            throw new Error('ImRuntime is already attached to another Root');
+        }
+        this.#snapshots = snapshots;
+    }
+    /**
+     * Optional Host AI / fallback path after Command miss (or non-prefixed text).
+     * Return true when the message was handled (reply already sent).
+     * `requester` is the Adapter Endpoint owner (for CapabilityIngress inheritance).
+     */
+    setUnmatchedHandler(handler) {
+        this.#unmatchedHandler = handler;
+    }
+    install(resources) {
+        resources.provide(messageGatewayToken, this);
+    }
+    /**
+     * 订阅消息事件（入站 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(input) {
+        const lease = this.#acquire();
+        let active = true;
+        try {
+            const requester = requireAdapters(lease.value).owner(input.adapter);
+            const message = new Message(input.adapter, input.target, input.content, lease.value.generation, (content, replyRequester = requester) => {
+                if (!active)
+                    throw new Error('Message reply scope has ended');
+                return this.#sendWithSnapshot({
+                    adapter: input.adapter,
+                    target: input.target,
+                    requester: replyRequester,
+                    content,
+                }, lease.value);
+            }, input.id, input.sender, Object.freeze({ ...input.metadata }));
+            let result = Object.freeze({ matched: false });
+            await runMiddleware(lease.value, message, async () => {
+                result = await this.#dispatcher.dispatch(message, lease.value);
+                if (!result.matched && this.#unmatchedHandler) {
+                    const handled = await this.#unmatchedHandler(message, lease.value, requester);
+                    if (handled) {
+                        result = Object.freeze({ matched: true, command: 'ai', owner: requester });
+                    }
+                }
+            }, 'inbound');
+            this.#emitMessage({
+                direction: 'inbound',
+                adapter: input.adapter,
+                target: input.target,
+                ...(input.sender !== undefined ? { sender: input.sender } : {}),
+                ...(channelTypeOf(input.target)
+                    ? { channelType: channelTypeOf(input.target) }
+                    : {}),
+                contentPreview: previewText(input.content),
+                ...(input.id !== undefined ? { messageId: input.id } : {}),
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        finally {
+            active = false;
+            lease.release();
+        }
+    }
+    async send(request) {
+        const lease = this.#acquire();
+        try {
+            return await this.#sendWithSnapshot(request, lease.value);
+        }
+        finally {
+            lease.release();
+        }
+    }
+    /** 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({
+                    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,
+                    managementCapabilities: row.managementCapabilities,
+                }));
+            }
+            finally {
+                lease.release();
+            }
+        }
+        catch {
+            return Object.freeze([]);
+        }
+    }
+    getEndpoint(adapter, endpointId) {
+        try {
+            const lease = this.#acquire();
+            try {
+                const index = requireAdapters(lease.value);
+                const id = index.resolve(adapter, endpointId);
+                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,
+                    managementCapabilities: row.managementCapabilities,
+                });
+            }
+            finally {
+                lease.release();
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    async sendEndpointMessage(input) {
+        const lease = this.#acquire();
+        try {
+            const index = requireAdapters(lease.value);
+            const capabilityId = index.resolve(input.adapter, input.endpointId);
+            if (!capabilityId)
+                throw new Error('endpoint not found');
+            const target = composeSendTarget(input.channelType, input.channelId);
+            const content = normalizeConsoleContent(input.content);
+            const result = await this.#sendWithSnapshot({
+                adapter: capabilityId,
+                target,
+                requester: index.owner(capabilityId),
+                content,
+                ...(input.parent ? { parent: input.parent } : {}),
+            }, lease.value);
+            return { messageId: result == null ? '' : String(result) };
+        }
+        finally {
+            lease.release();
+        }
+    }
+    /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
+    async addEndpointReaction(input) {
+        const endpoint = this.#liveEndpoint(input.adapter, input.endpointId);
+        if (!endpoint)
+            return null;
+        if (typeof endpoint.addReaction === 'function') {
+            return endpoint.addReaction(input.messageId, input.emoji, {
+                sceneType: input.sceneType,
+                channelId: input.channelId,
+            });
+        }
+        if (typeof endpoint.$addReaction === 'function') {
+            return endpoint.$addReaction(input.messageId, input.emoji, {
+                sceneType: input.sceneType,
+                channelId: input.channelId,
+            });
+        }
+        return null;
+    }
+    async removeEndpointReaction(input) {
+        const endpoint = this.#liveEndpoint(input.adapter, input.endpointId);
+        if (!endpoint)
+            return;
+        if (typeof endpoint.removeReaction === 'function') {
+            await endpoint.removeReaction(input.messageId, input.reactionId);
+            return;
+        }
+        if (typeof endpoint.$removeReaction === 'function') {
+            await endpoint.$removeReaction(input.messageId, input.reactionId);
+        }
+    }
+    /** Activity-feedback autoRemove: recall a previously sent status message. */
+    async recallEndpointMessage(input) {
+        const endpoint = this.#liveEndpoint(input.adapter, input.endpointId);
+        if (!endpoint)
+            return;
+        if (typeof endpoint.recallMessage === 'function') {
+            await endpoint.recallMessage(input.messageId);
+            return;
+        }
+        if (typeof endpoint.$recallMessage === 'function') {
+            await endpoint.$recallMessage(input.messageId);
+        }
+    }
+    #liveEndpoint(adapter, endpointId) {
+        try {
+            const lease = this.#acquire();
+            try {
+                const endpoint = requireAdapters(lease.value).instance(adapter, endpointId);
+                return endpoint ?? null;
+            }
+            finally {
+                lease.release();
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
+     * @deprecated Host callers should use `getEndpointManagement()`.
+     */
+    getLiveEndpoint(adapter, endpointId) {
+        return this.#liveEndpoint(adapter, endpointId);
+    }
+    /**
+     * Narrow Host seam for Console social/group management. An empty object means
+     * the Endpoint exists but implements no management operations; null means it
+     * cannot be resolved.
+     */
+    getEndpointManagement(adapter, endpointId) {
+        const endpoint = this.#liveEndpoint(adapter, endpointId);
+        if (!endpoint)
+            return null;
+        return resolveEndpointManagement(endpoint) ?? Object.freeze({});
+    }
+    async #sendWithSnapshot(request, snapshot) {
+        const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
+        // 单段对象 / html 段在此归一为适配器可消费的 wire 段数组；
+        // sandbox 适配器（控制台 UI）直接消费 html 段，跳过规范化。
+        const payload = isDirectHtmlConsumer(snapshot, request.adapter)
+            ? rendered
+            : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot));
+        const envelope = createOutboundEnvelope({
+            adapter: request.adapter,
+            target: request.target,
+            requester: request.requester,
+            generation: snapshot.generation,
+            ...(request.parent ? { parent: request.parent } : {}),
+        }, payload);
+        let result;
+        await runMiddleware(snapshot, envelope, async () => {
+            result = await requireAdapters(snapshot).send(request.adapter, {
+                target: request.target,
+                payload: envelope.payload,
+                ...(request.parent ? { parent: request.parent } : {}),
+            });
+        }, 'outbound');
+        this.#emitMessage({
+            direction: 'outbound',
+            adapter: request.adapter,
+            target: request.target,
+            requester: request.requester,
+            contentPreview: previewText(envelope.payload),
+            timestamp: Date.now(),
+        });
+        return result;
+    }
+    #acquire() {
+        if (!this.#snapshots)
+            throw new Error('ImRuntime is not attached to a Root');
+        return this.#snapshots.acquire();
+    }
+}
+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';
+}
+/**
+ * Build Adapter send target. If channelId already carries a scene prefix
+ * (`private:uid` / `group:gid`), do not double-prefix.
+ */
+function composeSendTarget(channelType, channelId) {
+    const id = channelId.trim();
+    if (!id)
+        return channelType || '';
+    if (/^(private|group|channel|direct|c2c|temp):/iu.test(id))
+        return id;
+    return channelType ? `${channelType}:${id}` : id;
+}
+/** `@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 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);
+}
+/** target 前缀场景：`group:123` → `group`；无前缀返回 undefined。 */
+function channelTypeOf(target) {
+    const match = /^([a-z0-9-]+):/iu.exec(target);
+    return match?.[1];
+}
+/** 消息内容 → 预览文本（截断 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);
+}

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

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './im-runtime.js';
+export * from './message-dispatcher.js';
+export * from './outbound-renderer.js';
+export * from './outbound-segments.js';

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

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './im-runtime.js';
+export * from './message-dispatcher.js';
+export * from './outbound-renderer.js';
+export * from './outbound-segments.js';

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

@@ -0,0 +1,17 @@
+import type { RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { Message, MessageDispatchResult } from './contracts.js';
+/**
+ * 命令前缀解析器：返回该消息要求的命令前缀。
+ * `''` 表示无前缀（任意文本都尝试按命令匹配）。
+ */
+export type CommandPrefixResolver = (message: Message, snapshot: RuntimeSnapshot) => string;
+/**
+ * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；
+ * 实例声明 `endpoints` 数组时，按消息 endpoint 名找 entry，`entry.commandPrefix` 覆盖顶层。
+ */
+export declare const defaultCommandPrefixResolver: CommandPrefixResolver;
+export declare class MessageDispatcher {
+    private readonly resolvePrefix;
+    constructor(resolvePrefix?: CommandPrefixResolver);
+    dispatch(message: Message, snapshot: RuntimeSnapshot): Promise<MessageDispatchResult>;
+}

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

@@ -0,0 +1,50 @@
+import { commandFeatureId, isCommandIndex } from '@zhin.js/command';
+function ownerOfMessage(message) {
+    return String(message.adapter).split('\0')[0];
+}
+/**
+ * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；
+ * 实例声明 `endpoints` 数组时，按消息 endpoint 名找 entry，`entry.commandPrefix` 覆盖顶层。
+ */
+export const defaultCommandPrefixResolver = (message, snapshot) => {
+    const config = snapshot.config.get(ownerOfMessage(message));
+    if (!config)
+        return '';
+    const endpointName = typeof message.metadata?.endpoint === 'string'
+        ? message.metadata.endpoint
+        : undefined;
+    if (endpointName && Array.isArray(config.endpoints)) {
+        const entry = config.endpoints.find((item) => !!item && typeof item === 'object'
+            && item.name === endpointName);
+        if (typeof entry?.commandPrefix === 'string')
+            return entry.commandPrefix;
+    }
+    return typeof config.commandPrefix === 'string' ? config.commandPrefix : '';
+};
+export class MessageDispatcher {
+    resolvePrefix;
+    constructor(resolvePrefix = defaultCommandPrefixResolver) {
+        this.resolvePrefix = resolvePrefix;
+    }
+    async dispatch(message, snapshot) {
+        const prefix = this.resolvePrefix(message, snapshot);
+        let input = message.content.trim();
+        if (prefix) {
+            if (!input.startsWith(prefix))
+                return Object.freeze({ matched: false });
+            input = input.slice(prefix.length).trim();
+        }
+        if (!input)
+            return Object.freeze({ matched: false });
+        const commands = snapshot.projections.get(commandFeatureId);
+        if (!isCommandIndex(commands))
+            return Object.freeze({ matched: false });
+        const result = await commands.dispatch(input, message);
+        if (result.matched && result.value !== undefined) {
+            if (!result.owner)
+                throw new Error('Matched Command is missing its owner');
+            await message.$replyFrom(result.owner, result.value);
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type SendContent } from './contracts.js';
+export declare class OutboundRenderer {
+    #private;
+    render(content: SendContent, requester: PluginId, snapshot: RuntimeSnapshot): Promise<unknown>;
+}

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

@@ -0,0 +1,31 @@
+import { componentFeatureId, isComponentIndex, } from '@zhin.js/component';
+import { isComponentCall, isRawContent, } from './contracts.js';
+const maxComponentDepth = 32;
+export class OutboundRenderer {
+    async render(content, requester, snapshot) {
+        return this.#render(content, requester, snapshot, 0);
+    }
+    async #render(content, requester, snapshot, depth) {
+        if (depth > maxComponentDepth)
+            throw new Error('Component render depth exceeded 32');
+        if (typeof content === 'string')
+            return content;
+        if (Array.isArray(content)) {
+            return Promise.all(content.map((item) => this.#render(item, requester, snapshot, depth)));
+        }
+        if (isRawContent(content))
+            return content.payload;
+        if (isComponentCall(content)) {
+            const rendered = await requireComponents(snapshot).render(requester, content.name, content.props);
+            return this.#render(rendered, requester, snapshot, depth + 1);
+        }
+        throw new TypeError('Unsupported SendContent');
+    }
+}
+function requireComponents(snapshot) {
+    const projection = snapshot.projections.get(componentFeatureId);
+    if (!isComponentIndex(projection)) {
+        throw new Error('Component Feature projection is not installed');
+    }
+    return projection;
+}

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

@@ -0,0 +1,22 @@
+import type { HtmlRendererHost } from '@zhin.js/plugin-runtime';
+/**
+ * Outbound payload normalization for the Plugin Runtime IM pipeline.
+ *
+ * `raw()` payloads reach adapters as-is; adapters only understand wire
+ * segments (`{ type, data }` arrays). A single segment object (non-array)
+ * would otherwise fall through to `String(payload)` → '[object Object]'.
+ * `html` segments additionally need a Host renderer: image when
+ * `@zhin.js/html-renderer` is installed, plain-text fallback otherwise.
+ */
+export interface OutboundSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
+/**
+ * Normalize a rendered outbound payload to wire segments:
+ * - segment arrays stay arrays (html segments converted per element);
+ * - a single segment object is wrapped into a one-element array;
+ * - anything else (plain strings, legacy `{ text }` shorthands) passes through.
+ */
+export declare function normalizeOutboundPayload(payload: unknown, renderer?: HtmlRendererHost): Promise<unknown>;