@zhin.js/core 1.3.5 → 1.4.1

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', 'file'],
+            description: 'url=http(s) 链接；path=本地文件路径；base64=内联 base64 数据；file=平台不透明文件引用（如 Telegram file_id）',
+        },
+        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/built/segment-contract/media.d.ts

@@ -1,4 +1,4 @@
-import type { MediaRef } from './types.js';
+import type { MediaRef, Segment } from './types.js';
 import { isMediaRef } from './validate.js';
 export { isMediaRef };
 export declare function mediaRefFromLegacyData(data: Record<string, unknown>): MediaRef | undefined;
@@ -6,3 +6,13 @@ export declare function mediaRefToLegacyFields(media: MediaRef): {
     url?: string;
     file?: string;
 };
+export interface SegmentMediaRef {
+    readonly type: string;
+    readonly media: MediaRef;
+}
+/**
+ * 从入站 canonical 段收集媒体引用（image / audio / video / file）。
+ * 兼容 canonical `data.media` 与旧轨 url/file/base64 字段；
+ * 无媒体段时返回空数组（调用方无需特判 undefined）。
+ */
+export declare function collectSegmentMedia(segments: readonly Segment[] | undefined): SegmentMediaRef[];

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

@@ -5,6 +5,13 @@ export function mediaRefFromLegacyData(data) {
         return data.media;
     }
     const mimeType = typeof data.mime_type === 'string' ? data.mime_type : undefined;
+    // 平台不透明文件引用（Telegram file_id / Milky resource_id 等）
+    const fileRef = typeof data.file_id === 'string' && data.file_id.trim()
+        ? data.file_id.trim()
+        : undefined;
+    if (fileRef) {
+        return { kind: 'file', value: fileRef, ...(mimeType ? { mime_type: mimeType } : {}) };
+    }
     const base64 = typeof data.base64 === 'string' && data.base64.trim()
         ? data.base64.trim()
         : typeof data.data === 'string' && data.data.trim() && !String(data.data).startsWith('http')
@@ -34,6 +41,29 @@ export function mediaRefToLegacyFields(media) {
         return { url: media.value, file: media.value };
     if (media.kind === 'path')
         return { file: media.value, url: media.value };
+    if (media.kind === 'file')
+        return { file: media.value, url: media.value };
     const encoded = media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
     return { file: encoded, url: encoded };
 }
+/** 入站段携带媒体引用的段类型（纯文本视图无法承载的信息）。 */
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
+/**
+ * 从入站 canonical 段收集媒体引用（image / audio / video / file）。
+ * 兼容 canonical `data.media` 与旧轨 url/file/base64 字段；
+ * 无媒体段时返回空数组（调用方无需特判 undefined）。
+ */
+export function collectSegmentMedia(segments) {
+    if (!segments?.length)
+        return [];
+    const out = [];
+    for (const segment of segments) {
+        if (!segment || typeof segment.type !== 'string' || !MEDIA_SEGMENT_TYPES.has(segment.type)) {
+            continue;
+        }
+        const media = mediaRefFromLegacyData(segment.data ?? {});
+        if (media)
+            out.push({ type: segment.type, media });
+    }
+    return out;
+}

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

@@ -0,0 +1,7 @@
+import type { Segment } from './types.js';
+/**
+ * 提取纯文本视图：text 段原文拼接，mention/at 段渲染为 `@name`（无名回退
+ * `@target`，`all` → `@all`）；其余段类型不产生文本（媒体 / 回复等结构化
+ * 信息经 `segments` 轨道消费，不污染命令输入）。
+ */
+export declare function segmentsToPlainText(segments: readonly Segment[]): string;

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

@@ -0,0 +1,34 @@
+/**
+ * Canonical Segment[] → 纯文本视图（SSOT）。
+ * 入站双轨：结构化段为唯一内部契约，纯文本视图供命令匹配 / AI 兜底消费。
+ * @see docs/architecture/segment-content-model.md
+ */
+import { readMentionName, readMentionTarget } from './mention.js';
+/**
+ * 提取纯文本视图：text 段原文拼接，mention/at 段渲染为 `@name`（无名回退
+ * `@target`，`all` → `@all`）；其余段类型不产生文本（媒体 / 回复等结构化
+ * 信息经 `segments` 轨道消费，不污染命令输入）。
+ */
+export function segmentsToPlainText(segments) {
+    let out = '';
+    for (const segment of segments) {
+        // Segment 含 SegmentBase 兜底成员，type 窄化不能联动窄化 data，统一按字典读
+        const data = segment.data;
+        if (segment.type === 'text') {
+            if (typeof data.text === 'string')
+                out += data.text;
+            continue;
+        }
+        if (segment.type === 'mention' || segment.type === 'at') {
+            const name = readMentionName(data);
+            if (name) {
+                out += `@${name}`;
+                continue;
+            }
+            const target = readMentionTarget(data);
+            if (target)
+                out += `@${target}`;
+        }
+    }
+    return out;
+}

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

@@ -7,9 +7,13 @@ export interface SegmentBase {
     data: Record<string, unknown>;
     platform?: Record<string, unknown>;
 }
-/** 媒体引用占位（完整 schema 随 adapter 迁移补齐） */
+/**
+ * 媒体引用占位（完整 schema 随 adapter 迁移补齐）。
+ * kind=file：平台侧不透明文件引用（如 Telegram file_id、Milky resource_id），
+ * 非 URL/本地路径，消费方需经平台 API 解析。
+ */
 export interface MediaRef {
-    kind: 'url' | 'path' | 'base64';
+    kind: 'url' | 'path' | 'base64' | 'file';
     value: string;
     mime_type?: string;
 }

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

@@ -4,6 +4,7 @@ const mediaKindSchema = Schema.union([
     Schema.const('url'),
     Schema.const('path'),
     Schema.const('base64'),
+    Schema.const('file'),
 ]);
 export const mediaRefSchema = Schema.object({
     kind: mediaKindSchema.required(),

package/lib/command.d.ts

@@ -5,8 +5,11 @@ import { Plugin } from './plugin.js';
 type ConstructFirstParam<T extends new (...args: any[]) => any> = T extends new (...args: [infer U, ...any[]]) => any ? U : never;
 type ConstructSecondParam<T extends new (...args: any[]) => any> = T extends new (...args: [any, infer V, ...any[]]) => any ? V : never;
 /**
- * MessageCommand类：命令系统核心，基于segment-matcher实现。
- * 支持多平台命令注册、作用域限制、参数解析、异步处理等。
+ * MessageCommand类：经典命令系统（segment-matcher）。
+ *
+ * @deprecated 新插件请用 `defineCommand`（`zhin.js/command`）+ `commands/` 约定目录。
+ * 本类仍供 Agent init / game-kit hub / legacy `CommandFeature` 使用；计划随经典
+ * Plugin 路径一并退役。见 `docs/contributing/public-api-surface.md`。
  */
 export declare class MessageCommand<T extends RegisteredAdapter = RegisteredAdapter> extends SegmentMatcher {
     #private;

package/lib/command.js

@@ -1,7 +1,10 @@
 import { SegmentMatcher } from 'segment-matcher';
 /**
- * MessageCommand类：命令系统核心，基于segment-matcher实现。
- * 支持多平台命令注册、作用域限制、参数解析、异步处理等。
+ * MessageCommand类：经典命令系统（segment-matcher）。
+ *
+ * @deprecated 新插件请用 `defineCommand`（`zhin.js/command`）+ `commands/` 约定目录。
+ * 本类仍供 Agent init / game-kit hub / legacy `CommandFeature` 使用；计划随经典
+ * Plugin 路径一并退役。见 `docs/contributing/public-api-surface.md`。
  */
 export class MessageCommand extends SegmentMatcher {
     #callbacks = [];

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/feature/adapter.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Adapter Feature — implementation in `@zhin.js/adapter`. */
+export * from '@zhin.js/adapter';

package/lib/feature/adapter.js

@@ -0,0 +1,2 @@
+/** Authoring API for Adapter Feature — implementation in `@zhin.js/adapter`. */
+export * from '@zhin.js/adapter';

package/lib/feature/command.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Command Feature — implementation in `@zhin.js/command`. */
+export * from '@zhin.js/command';

package/lib/feature/command.js

@@ -0,0 +1,2 @@
+/** Authoring API for Command Feature — implementation in `@zhin.js/command`. */
+export * from '@zhin.js/command';

package/lib/feature/component.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Component Feature — implementation in `@zhin.js/component`. */
+export * from '@zhin.js/component';

package/lib/feature/component.js

@@ -0,0 +1,2 @@
+/** Authoring API for Component Feature — implementation in `@zhin.js/component`. */
+export * from '@zhin.js/component';

package/lib/feature/middleware.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Middleware Feature — implementation in `@zhin.js/middleware`. */
+export * from '@zhin.js/middleware';

package/lib/feature/middleware.js

@@ -0,0 +1,2 @@
+/** Authoring API for Middleware Feature — implementation in `@zhin.js/middleware`. */
+export * from '@zhin.js/middleware';

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

@@ -1,4 +1,6 @@
-import type { CapabilityId, PluginId } from '@zhin.js/plugin-runtime';
+import type { CapabilityId, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+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> {
@@ -18,7 +20,18 @@ export declare function isRawContent(value: SendContent): value is RawContent;
 export interface IncomingMessage {
     readonly adapter: CapabilityId;
     readonly target: string;
+    /**
+     * 纯文本视图：与 `segments` 同源（adapter 从同一份入站载荷派生二者）。
+     * 触发判定与 Console 预览读取此字段；命令匹配在有 segments 时优先使用结构化视图。
+     */
     readonly content: string;
+    /**
+     * 结构化段视图（canonical Segment SSOT，见 built/segment-contract）。
+     * 与 `content` 同源：segments 承载纯文本无法表达的媒体（image/audio/video/file
+     * 的 MediaRef）、mention、reply 等信息。旧 adapter 未迁移时可缺省，
+     * 读取方必须容忍 undefined。
+     */
+    readonly segments?: readonly Segment[];
     readonly id?: string;
     readonly sender?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -48,6 +61,18 @@ export interface OutboundEnvelope {
 export interface MessageGateway {
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
     send(request: SendRequest): Promise<unknown>;
+    /**
+     * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
+     * 平台 callback 的 action 段、'text' 端点的数字回跳与指令预填直出
+     * payload 都会路由到这里。
+     */
+    registerInteractiveHandler(prefix: string, handler: (message: Message) => Promise<boolean> | boolean): () => void;
+    /**
+     * Command miss（或非前缀文本）后的回退处理：Host AI 对话、单文件 bot 用。
+     * 返回 true 表示已处理（回复已发送）；后注册者覆盖前者。
+     * `requester` 是消息所属 Adapter Endpoint 的 owner（用于 CapabilityIngress 继承）。
+     */
+    setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
 }
 export interface MessageDispatchResult {
     readonly matched: boolean;
@@ -63,9 +88,18 @@ export declare class Message {
     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>>);
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    readonly segments?: readonly Segment[] | 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>;
 }
 export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;
-export {};

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

@@ -30,7 +30,13 @@ export class Message {
     id;
     sender;
     metadata;
-    constructor(adapter, target, content, generation, reply, id, sender, metadata = Object.freeze({})) {
+    segments;
+    constructor(adapter, target, content, generation, reply, id, sender, metadata = Object.freeze({}), 
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    segments) {
         this.adapter = adapter;
         this.target = target;
         this.content = content;
@@ -38,6 +44,7 @@ export class Message {
         this.id = id;
         this.sender = sender;
         this.metadata = metadata;
+        this.segments = segments;
         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,8 +1,31 @@
-import { Scope, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+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';
+import { type RuntimeInteractiveHandler } from './interactive.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;
 }
@@ -17,15 +40,27 @@ export declare class ImRuntime implements MessageGateway {
      */
     setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
     install(resources: Scope): void;
+    /**
+     * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
+     * 在 Command dispatch 之前路由：action 段 / 数字回跳 / 指令预填 payload。
+     */
+    registerInteractiveHandler(prefix: string, handler: RuntimeInteractiveHandler): () => 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;
@@ -33,6 +68,7 @@ export declare class ImRuntime implements MessageGateway {
         readonly connected: boolean;
         readonly status: 'online' | 'offline';
         readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+        readonly managementCapabilities: readonly EndpointManagementCapability[];
     } | null;
     sendEndpointMessage(input: {
         readonly adapter: string;
@@ -65,6 +101,15 @@ export declare class ImRuntime implements MessageGateway {
         readonly endpointId: string;
         readonly messageId: string;
     }): Promise<void>;
-    /** Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。 */
+    /**
+     * 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;
 }