@zhin.js/core 1.4.3 → 1.5.0

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

@@ -1,4 +1,5 @@
 import type { CapabilityId, PluginId, RuntimeSnapshot } 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";
@@ -12,13 +13,23 @@ export interface RawContent<TPayload = unknown> {
     readonly $content: typeof rawContentBrand;
     readonly payload: TPayload;
 }
-export type SendContent = string | ComponentCall | RawContent | readonly SendContent[];
+/**
+ * 出站内容：纯文本 / 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 IncomingMessage {
     readonly adapter: CapabilityId;
+    /** Structured identity supplied by migrated adapters; target remains the bridge. */
+    readonly conversation?: ConversationRef;
+    /** Structured native message identity supplied by migrated adapters. */
+    readonly message?: MessageRef;
     readonly target: string;
     /**
      * 纯文本视图：与 `segments` 同源（adapter 从同一份入站载荷派生二者）。
@@ -38,6 +49,8 @@ export interface IncomingMessage {
 }
 export interface SendRequest {
     readonly adapter: CapabilityId;
+    /** Structured destination supplied to Adapter endpoints in parallel with target. */
+    readonly conversation?: ConversationRef;
     readonly target: string;
     readonly requester: PluginId;
     readonly content: SendContent;
@@ -51,6 +64,7 @@ export interface ChannelParent {
 }
 export interface OutboundEnvelope {
     readonly adapter: CapabilityId;
+    readonly conversation?: ConversationRef;
     readonly target: string;
     readonly requester: PluginId;
     readonly generation: number;
@@ -60,6 +74,10 @@ export interface OutboundEnvelope {
 }
 export interface MessageGateway {
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
+    /**
+     * Compatibility surface for existing Adapter-facing gateway consumers.
+     * Runtime callers that need an outcome use DeliveryMessageGateway instead.
+     */
     send(request: SendRequest): Promise<unknown>;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
@@ -74,6 +92,10 @@ export interface MessageGateway {
      */
     setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
 }
+/** Structured outbound gateway exposed by the Plugin Runtime. */
+export interface DeliveryMessageGateway extends MessageGateway {
+    send(request: SendRequest): Promise<DeliveryReceipt>;
+}
 export interface MessageDispatchResult {
     readonly matched: boolean;
     readonly command?: string;
@@ -93,13 +115,21 @@ export declare class Message {
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
     readonly segments?: readonly Segment[] | undefined;
+    /** Structured inbound conversation when supplied by a migrated adapter. */
+    readonly conversation?: ConversationRef | undefined;
+    /** Structured inbound message identity when supplied by a migrated adapter. */
+    readonly message?: MessageRef | undefined;
     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>>, 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
-    segments?: readonly Segment[] | undefined);
-    readonly $reply: (content: SendContent) => Promise<unknown>;
-    readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<unknown>;
+    segments?: readonly Segment[] | undefined, 
+    /** Structured inbound conversation when supplied by a migrated adapter. */
+    conversation?: ConversationRef | undefined, 
+    /** Structured inbound message identity when supplied by a migrated adapter. */
+    message?: MessageRef | undefined);
+    readonly $reply: (content: SendContent) => Promise<DeliveryReceipt>;
+    readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<DeliveryReceipt>;
 }
 export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;

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

@@ -22,6 +22,16 @@ export function isRawContent(value) {
         && '$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 {
     adapter;
     target;
@@ -31,12 +41,22 @@ export class Message {
     sender;
     metadata;
     segments;
-    constructor(adapter, target, content, generation, reply, id, sender, metadata = Object.freeze({}), 
+    conversation;
+    message;
+    constructor(adapter, target, content, generation, 
+    // Compatibility at the construction boundary: legacy tests and embedders
+    // may still supply an untyped reply callback. ImRuntime always supplies a
+    // DeliveryReceipt-producing implementation.
+    reply, id, sender, metadata = Object.freeze({}), 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
-    segments) {
+    segments, 
+    /** Structured inbound conversation when supplied by a migrated adapter. */
+    conversation, 
+    /** Structured inbound message identity when supplied by a migrated adapter. */
+    message) {
         this.adapter = adapter;
         this.target = target;
         this.content = content;
@@ -45,6 +65,8 @@ export class Message {
         this.sender = sender;
         this.metadata = metadata;
         this.segments = segments;
+        this.conversation = conversation;
+        this.message = message;
         this.$reply = (content) => reply(content);
         this.$replyFrom = (requester, content) => reply(content, requester);
         Object.freeze(this);

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

@@ -1,9 +1,10 @@
 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 { type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
+import { Message, type ChannelParent, type DeliveryMessageGateway, type IncomingMessage, type MessageDispatchResult, type SendRequest } from './contracts.js';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { type RuntimeInteractiveHandler } from './interactive.js';
-export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
+export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<DeliveryMessageGateway>;
 /** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
 export interface RuntimeMessageEvent {
     readonly direction: 'inbound' | 'outbound';
@@ -29,7 +30,7 @@ export interface ImRuntimeOptions {
     readonly commandPrefix?: string;
     readonly renderer?: OutboundRenderer;
 }
-export declare class ImRuntime implements MessageGateway {
+export declare class ImRuntime implements DeliveryMessageGateway {
     #private;
     constructor(options?: ImRuntimeOptions);
     attach(snapshots: SnapshotStore): void;
@@ -51,7 +52,7 @@ export declare class ImRuntime implements MessageGateway {
      */
     onMessage(listener: (event: RuntimeMessageEvent) => void): () => void;
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
-    send(request: SendRequest): Promise<unknown>;
+    send(request: SendRequest): Promise<DeliveryReceipt>;
     /** Console `endpoint.list` — empty until Adapter Feature projection is ready. */
     listEndpoints(): readonly {
         readonly name: string;
@@ -73,8 +74,9 @@ export declare class ImRuntime implements MessageGateway {
     sendEndpointMessage(input: {
         readonly adapter: string;
         readonly endpointId: string;
-        readonly channelId: string;
-        readonly channelType: string;
+        readonly conversation?: ConversationRef;
+        readonly channelId?: string;
+        readonly channelType?: string;
         readonly content: unknown;
         readonly parent?: ChannelParent;
     }): Promise<{
@@ -84,7 +86,8 @@ export declare class ImRuntime implements MessageGateway {
     addEndpointReaction(input: {
         readonly adapter: string;
         readonly endpointId: string;
-        readonly messageId: string;
+        readonly message?: MessageRef;
+        readonly messageId?: string;
         readonly emoji: string;
         readonly sceneType?: string;
         readonly channelId?: string;
@@ -92,14 +95,30 @@ export declare class ImRuntime implements MessageGateway {
     removeEndpointReaction(input: {
         readonly adapter: string;
         readonly endpointId: string;
-        readonly messageId: string;
+        readonly message?: MessageRef;
+        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;
+        readonly message?: MessageRef;
+        readonly messageId?: string;
+    }): Promise<void>;
+    editEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly message?: MessageRef;
+        readonly messageId?: string;
+        readonly content: unknown;
+    }): Promise<string | null>;
+    setEndpointTyping(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly conversation?: ConversationRef;
+        readonly target?: string;
+        readonly active?: boolean;
     }): Promise<void>;
     /**
      * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。

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

@@ -1,11 +1,13 @@
 import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
-import { adapterFeatureId, isAdapterIndex, resolveEndpointManagement, } from '@zhin.js/adapter';
+import { adapterFeatureId, isAdapterIndex, resolveEndpointControl, resolveEndpointManagement, } from '@zhin.js/adapter';
+import { formatLegacyConversationRef, formatLegacyMessageRef, isDeliveryReceipt, } from '@zhin.js/im-contract';
 import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
 import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
 import { Message, createOutboundEnvelope, } from './contracts.js';
 import { defaultCommandPrefixResolver, MessageDispatcher } from './message-dispatcher.js';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { applyOutboundInteractivePolicy, normalizeOutboundPayload, resolveOutboundInteractivePolicy, resolveOutboundMediaPolicy, } from './outbound-segments.js';
+import { assertCanonicalSegments } from '../../built/segment-contract/assert.js';
 import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
 import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveChannelKey, } from './interactive.js';
 const logger = getLogger('im');
@@ -92,11 +94,12 @@ export class ImRuntime {
                     throw new Error('Message reply scope has ended');
                 return this.#sendWithSnapshot({
                     adapter: input.adapter,
+                    ...(input.conversation ? { conversation: input.conversation } : {}),
                     target: input.target,
                     requester: replyRequester,
                     content,
                 }, lease.value);
-            }, input.id, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined);
+            }, input.id ?? input.message?.id, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.conversation, input.message);
             let result = Object.freeze({ matched: false });
             await runMiddleware(lease.value, message, async () => {
                 result = await this.#dispatchInteractive(message, requester)
@@ -130,7 +133,9 @@ export class ImRuntime {
                     ? { channelType: channelTypeOf(input.target) }
                     : {}),
                 contentPreview: previewText(input.content),
-                ...(input.id !== undefined ? { messageId: input.id } : {}),
+                ...(input.id ?? input.message?.id
+                    ? { messageId: input.id ?? input.message?.id }
+                    : {}),
                 timestamp: Date.now(),
             });
             return result;
@@ -210,16 +215,21 @@ export class ImRuntime {
             const capabilityId = index.resolve(input.adapter, input.endpointId);
             if (!capabilityId)
                 throw new Error('endpoint not found');
-            const target = composeSendTarget(input.channelType, input.channelId);
+            const target = input.conversation
+                ? formatLegacyConversationRef(input.conversation)
+                : composeSendTarget(input.channelType ?? '', input.channelId ?? '');
+            if (!target)
+                throw new TypeError('conversation or channelId is required');
             const content = normalizeConsoleContent(input.content);
             const result = await this.#sendWithSnapshot({
                 adapter: capabilityId,
+                ...(input.conversation ? { conversation: input.conversation } : {}),
                 target,
                 requester: index.owner(capabilityId),
                 content,
                 ...(input.parent ? { parent: input.parent } : {}),
             }, lease.value);
-            return { messageId: result == null ? '' : String(result) };
+            return { messageId: result.message?.id ?? result.legacyMessageId ?? '' };
         }
         finally {
             lease.release();
@@ -227,47 +237,33 @@ export class ImRuntime {
     }
     /** 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;
+        const control = this.#liveEndpointControl(input.adapter, input.endpointId);
+        return control?.addReaction?.(legacyMessageTarget(input.message, input.messageId), input.emoji, {
+            sceneType: input.sceneType,
+            channelId: input.channelId,
+        }) ?? 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);
-        }
+        await this.#liveEndpointControl(input.adapter, input.endpointId)
+            ?.removeReaction?.(legacyMessageTarget(input.message, 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);
-        }
+        await this.#liveEndpointControl(input.adapter, input.endpointId)
+            ?.recall?.(legacyMessageTarget(input.message, input.messageId));
+    }
+    async editEndpointMessage(input) {
+        return this.#liveEndpointControl(input.adapter, input.endpointId)
+            ?.edit?.(legacyMessageTarget(input.message, input.messageId), input.content) ?? null;
+    }
+    async setEndpointTyping(input) {
+        const target = input.conversation
+            ? formatLegacyConversationRef(input.conversation)
+            : input.target;
+        if (!target)
+            throw new TypeError('conversation or target is required');
+        await this.#liveEndpointControl(input.adapter, input.endpointId)
+            ?.typing?.(target, input.active);
     }
     #liveEndpoint(adapter, endpointId) {
         try {
@@ -284,6 +280,10 @@ export class ImRuntime {
             return null;
         }
     }
+    #liveEndpointControl(adapter, endpointId) {
+        const endpoint = this.#liveEndpoint(adapter, endpointId);
+        return resolveEndpointControl(endpoint) ?? null;
+    }
     /**
      * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
      * @deprecated Host callers should use `getEndpointManagement()`.
@@ -303,41 +303,72 @@ export class ImRuntime {
         return resolveEndpointManagement(endpoint) ?? Object.freeze({});
     }
     async #sendWithSnapshot(request, snapshot) {
-        const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
-        // 单段对象 / html 段在此归一为适配器可消费的 canonical 段数组（含媒体能力协商）；
-        // sandbox 适配器（控制台 UI）直接消费 html 段，跳过规范化。
-        let payload = isDirectHtmlConsumer(snapshot, request.adapter)
-            ? rendered
-            : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot), {
-                mediaPolicy: resolveOutboundMediaPolicy(request.adapter, snapshot),
-            });
-        // interactive 中央执行：'text' 端点 keyboard → 编号文本，fallback 映射写
-        // 中央存储（入站数字回跳解析用）；'native' 端点透传 keyboard。
-        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(request.adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveChannelKey(String(request.adapter), request.target), map));
+        let initialPayload;
+        try {
+            const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
+            initialPayload = await prepareOutboundPayload(rendered, request, snapshot);
+        }
+        catch {
+            return rejectedReceipt('outbound_payload_rejected');
+        }
         const envelope = createOutboundEnvelope({
             adapter: request.adapter,
+            ...(request.conversation ? { conversation: request.conversation } : {}),
             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;
+        }, initialPayload);
+        let terminalEntered = false;
+        let receipt;
+        try {
+            await runMiddleware(snapshot, envelope, async () => {
+                terminalEntered = true;
+                let payload;
+                try {
+                    // Middleware may replace a payload with legacy/wire segments. Normalize
+                    // again at the transport boundary so it cannot bypass core policy.
+                    payload = await prepareOutboundPayload(envelope.payload, request, snapshot, true);
+                }
+                catch {
+                    receipt = rejectedReceipt('outbound_payload_rejected');
+                    return;
+                }
+                try {
+                    const result = await requireAdapters(snapshot).send(request.adapter, {
+                        target: request.target,
+                        ...(request.conversation ? { conversation: request.conversation } : {}),
+                        payload,
+                        ...(request.parent ? { parent: request.parent } : {}),
+                    });
+                    receipt = receiptFromEndpointResult(result);
+                }
+                catch (error) {
+                    receipt = receiptFromEndpointError(error);
+                }
+                if (receipt?.status === 'sent') {
+                    this.#emitMessage({
+                        direction: 'outbound',
+                        adapter: request.adapter,
+                        target: request.target,
+                        requester: request.requester,
+                        contentPreview: previewText(payload),
+                        ...(receipt.message?.id || receipt.legacyMessageId
+                            ? { messageId: receipt.message?.id ?? receipt.legacyMessageId }
+                            : {}),
+                        timestamp: Date.now(),
+                    });
+                }
+            }, 'outbound');
+        }
+        catch {
+            // If a middleware fails after the terminal, the endpoint has already
+            // produced its receipt (and, for a real send, its event). Keep that fact.
+            return receipt ?? failedReceipt('outbound_middleware_failed');
+        }
+        if (!terminalEntered)
+            return suppressedReceipt();
+        return receipt ?? failedReceipt('outbound_delivery_incomplete');
     }
     #acquire() {
         if (!this.#snapshots)
@@ -385,6 +416,80 @@ function isDirectHtmlConsumer(snapshot, adapter) {
     const owner = snapshot.capabilities.get(adapter)?.owner;
     return adapterTypeName(snapshot.tree.get(owner)?.packageName) === 'sandbox';
 }
+function legacyMessageTarget(message, messageId) {
+    if (message)
+        return formatLegacyMessageRef(message);
+    if (messageId)
+        return messageId;
+    throw new TypeError('message or messageId is required');
+}
+async function prepareOutboundPayload(rendered, request, snapshot, finalizeInteractive = false) {
+    const directHtml = isDirectHtmlConsumer(snapshot, request.adapter);
+    let payload = directHtml
+        ? rendered
+        : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot), {
+            mediaPolicy: resolveOutboundMediaPolicy(request.adapter, snapshot),
+        });
+    if (finalizeInteractive) {
+        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(request.adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveChannelKey(String(request.adapter), request.target), map));
+    }
+    // Segment arrays crossing the adapter boundary are canonical after every
+    // middleware transform. Direct html consumers retain their explicit wire API.
+    if (!directHtml && Array.isArray(payload))
+        assertCanonicalSegments(payload);
+    return payload;
+}
+function receiptFromEndpointResult(result) {
+    if (isDeliveryReceipt(result))
+        return result;
+    const legacyMessageId = legacyMessageIdOf(result);
+    return Object.freeze({
+        status: 'sent',
+        ...(legacyMessageId ? { legacyMessageId } : {}),
+    });
+}
+function legacyMessageIdOf(result) {
+    if (typeof result === 'string' || typeof result === 'number')
+        return String(result);
+    if (!result || typeof result !== 'object')
+        return undefined;
+    const id = result.id;
+    return typeof id === 'string' || typeof id === 'number' ? String(id) : undefined;
+}
+function receiptFromEndpointError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/Unknown Adapter Endpoint|does not support outbound/u.test(message)) {
+        return unsupportedReceipt('outbound_unsupported');
+    }
+    if (/not active/u.test(message))
+        return failedReceipt('endpoint_inactive', true);
+    return failedReceipt('endpoint_send_failed', true);
+}
+function suppressedReceipt() {
+    return Object.freeze({ status: 'suppressed' });
+}
+function unsupportedReceipt(code) {
+    return Object.freeze({
+        status: 'unsupported',
+        failure: Object.freeze({ code, message: 'Outbound delivery is not supported.' }),
+    });
+}
+function rejectedReceipt(code) {
+    return Object.freeze({
+        status: 'rejected',
+        failure: Object.freeze({ code, message: 'Outbound payload was rejected.' }),
+    });
+}
+function failedReceipt(code, retryable = false) {
+    return Object.freeze({
+        status: 'failed',
+        failure: Object.freeze({
+            code,
+            message: 'Outbound delivery failed.',
+            ...(retryable ? { retryable: true } : {}),
+        }),
+    });
+}
 /**
  * Build Adapter send target. If channelId already carries a scene prefix
  * (`private:uid` / `group:gid`), do not double-prefix.

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

@@ -1,5 +1,5 @@
 import { componentFeatureId, isComponentIndex, } from '@zhin.js/component';
-import { isComponentCall, isRawContent, } from './contracts.js';
+import { isComponentCall, isRawContent, isSegmentContent, } from './contracts.js';
 const maxComponentDepth = 32;
 export class OutboundRenderer {
     async render(content, requester, snapshot) {
@@ -15,6 +15,9 @@ export class OutboundRenderer {
         }
         if (isRawContent(content))
             return content.payload;
+        // canonical Segment 一等公民：原样透传，由下游 normalizeOutboundPayload 归一与协商
+        if (isSegmentContent(content))
+            return content;
         if (isComponentCall(content)) {
             const rendered = await requireComponents(snapshot).render(requester, content.name, content.props);
             return this.#render(rendered, requester, snapshot, depth + 1);

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

@@ -20,34 +20,33 @@ export interface OutboundSegment {
 }
 /**
  * 出站媒体能力策略（html→image 渲染产物与 base64/path 媒体段的投递方式）：
- * - `base64`：平台接受 base64 直发（qq / icqq / slack / weixin-ilink）；
+ * - `base64`：平台接受 base64 直发；
  * - `url-or-text`：平台仅接受 URL 媒体；本层无上传通道，base64/path → 文本降级；
- * - `passthrough`：adapter 自行物化媒体（napcat / onebot11 / onebot12），本层不动。
+ * - `passthrough`：adapter 自行物化媒体，本层不动。
  */
 export type OutboundMediaPolicy = 'base64' | 'url-or-text' | 'passthrough';
 /**
- * 任务 C `defineAdapter` segments policy 挂载形状（duck-typed 读取）。
- * 契约形状为 `outboundMedia: readonly ('url'|'path'|'base64'|'upload')[]`
- * （端点可消费的媒体来源形式，见 `@zhin.js/adapter` 的 AdapterSegmentPolicy）；
- * 兼容过渡期的单值策略字符串。Adapter 在 definition 上声明
- * `segments: { outboundMedia }` 即覆盖内置表。
+ * adapter definition 的 segments policy 声明（必选能力面）。
+ * `outboundMedia` 为端点可消费的媒体来源形式数组
+ * （'url' | 'path' | 'base64' | 'upload'），映射到投递策略：
+ * base64 可直发；无 base64 但端点可自行物化（upload/path）→ passthrough；
+ * 仅 url → 非 URL 媒体文本降级。未声明的 adapter 按 ['url'] 兜底。
  */
 export interface OutboundSegmentsPolicy {
-    readonly outboundMedia?: OutboundMediaPolicy | readonly ('url' | 'path' | 'base64' | 'upload')[];
+    readonly outboundMedia: readonly ('url' | 'path' | 'base64' | 'upload')[];
     readonly interactive?: InteractivePolicy;
 }
 export interface NormalizeOutboundOptions {
-    /** 缺省 `base64`（保持历史行为：html→image base64 直发）。 */
+    /** 缺省 `url-or-text`（未声明 adapter 的保守兜底：仅 URL 媒体可达）。 */
     readonly mediaPolicy?: OutboundMediaPolicy;
 }
-export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
 /**
- * 解析端点的出站媒体策略：优先读 adapter definition 上声明的
- * `segments.outboundMedia`（任务 C 挂载点；多 endpoint 展开的 `slot~entry`
- * id 回退到 slot id 查声明），否则按平台名查内置表，
- * 未知平台回退 `base64`（历史行为）。
+ * 解析端点的出站媒体策略：读 adapter definition 声明的 `segments.outboundMedia`
+ * （多 endpoint 展开的 `slot~entry` id 回退到 slot id 查声明）；
+ * 未声明回退 `url-or-text`（仅 URL 媒体可达，其余文本降级）。
  */
 export declare function resolveOutboundMediaPolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): OutboundMediaPolicy;
+export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
 /**
  * 解析端点的出站 interactive 策略：优先读 adapter definition 上声明的
  * `segments.interactive`，否则按平台名查内置表，未知平台回退 'text'。