@zhin.js/adapter 1.1.11 → 1.2.1

package/README.md

@@ -22,12 +22,39 @@ export default defineAdapter({
 单文件插件可用 `setup({ addAdapter })` 注册 `defineAdapter(...)`；Endpoint 仍由同一个
 AdapterIndex 和 generation lifecycle 管理。
 
+## Adapter 与 Endpoint 职责
+
+二者不是同一个运行时对象的两种叫法。固定职责如下：
+
+| Module | 负责 | 禁止承担 |
+| --- | --- | --- |
+| Adapter definition | 声明平台能力与段策略；解析单个 endpoint 配置；注入依赖；选择并构造一种 Endpoint implementation | 建连、收发消息、持有 socket/timer/listener、维护在线状态、保存 live Endpoint Map |
+| Endpoint instance | 代表一个具体账号/连接；拥有 transport、协议编解码、send/control/content/management、start/open/close/stop 与资源清理 | 展开多账号配置、查找兄弟 Endpoint、发布 generation、维护全局 registry、执行 endpoint add/edit/remove 配置命令 |
+| AdapterIndex | 展开 1:N 配置；作为当前 generation 的 Endpoint directory；校验能力；编排 admission 与生命周期；提供 Runtime 查询 | 理解平台协议、鉴权、媒体上传或 SDK 类型 |
+| Plugin composition | 提供 schema、Resource、命令、HTTP Host 和平台专属 Agent tools | 绕过 AdapterIndex 保存另一份 live Endpoint 权威状态 |
+
+`defineAdapter().create()` 是 Adapter 与 Endpoint 的唯一 Seam：调用前属于配置、能力和
+依赖装配，返回后属于具体 Endpoint 的运行期。Adapter definition 应保持无连接状态；
+Endpoint 不得把自己注册进模块级 Map。需要从命令、Agent tool 或 Host 查找当前 Endpoint
+时，应解析当前 generation 的 AdapterIndex/Resource View，不能建立 second source of truth。
+
+旧 `@zhin.js/core` 的 `Adapter` class 同时承担集合、消息管线、发送和 Registry，属于兼容
+外壳，不是 Plugin Runtime 的 authoring model。新代码不得依赖、继承或伪造该 class；运行
+期协作应依赖 `OutboundMessageService`、`OutboundHost`、`EndpointControl` 等窄 Interface。
+`pnpm check:adapter-endpoint-boundaries` 对现存 legacy Adapter consumer 与模块级 Agent
+Endpoint registry 使用基线 allowlist 做单调收缩门禁：允许逐项删除，但禁止新增。
+
 ## Transport Contract
 
 Adapter definitions declare `capabilities` for inbound/outbound admission and
 `operations` for optional actions such as `recall`, `edit`, `reaction`, and
-`typing`. Runtime callers should query the resulting `EndpointCapabilities`
-instead of probing optional endpoint methods. The zero-dependency types live in
+`typing`. `operations` accepts either a static list or a resolver receiving the
+concrete `AdapterContext`; use the resolver when connection modes expose different
+operations. `AdapterIndex` resolves, freezes, and exposes the exact set for every
+expanded Endpoint. Runtime callers should query the resulting `EndpointCapabilities`
+instead of probing optional endpoint methods. Declarations and the explicit
+`EndpointControl` port are validated in both directions, so hidden or unimplemented
+operations fail candidate generation before commit. The zero-dependency types live in
 [`@zhin.js/im-contract`](../im-contract/README.md).
 
 Framework-facing outbound code carries a structured `ConversationRef`.
@@ -38,14 +65,39 @@ non-empty platform message id. IM Runtime alone wraps that id as a structured
 
 ## Endpoint Control Port
 
-`EndpointInstance.control` owns actions addressed to an existing message:
+`Endpoint.control` owns actions addressed to an existing message:
 `recall`, `addReaction`, and `removeReaction`. IM Core consumes only this port;
 adapter-specific method names and compound message ids stay at the protocol
 boundary.
 
 New adapters should provide `control` directly and declare matching
 `operations`. Protocol-specific methods and compound string identifiers are not
-inspected or adapted by the runtime.
+inspected by the runtime. `createRecallEndpointControl()` bridges the common
+platform `recall(messageId)` shape without leaking that shape into Core.
+
+## Operation-scoped Client resolution
+
+每个平台包公开一个由 `defineEndpointClient<Client, EventMap>()` 创建的 token，并通过
+`AdapterClientRegistry` 注册 Client/EventMap 类型。当前 IM operation 不需要手动查找
+Endpoint：Handler 的事件参数直接携带 `client`，Command、Middleware 和 Agent Tool 的
+`context.$client` 是按需解析的属性 getter：
+
+```ts
+defineCommand({
+  adapter: 'icqq',
+  execute(context) {
+    return context.$client.getGroupList();
+  },
+});
+
+const client = icqqClient.get(context, id);  // task / schedule / Host / 跨账号
+const client = icqqClient.find(context, id); // 可选显式查找；不存在时返回 undefined
+```
+
+声明字面量 `adapter` 后 `$client` 会反射为确切 Client；不声明时保持 `unknown`。
+Token 的 `get()` 会校验 Endpoint adapter，并从当前 generation 的 AdapterIndex 解析；
+返回值不得缓存到当前 operation 之外。平台 SDK 方法直接在 Client 上调用，Endpoint 不复制
+SDK interface。普通消息发送仍必须走统一 outbound chain。
 
 ## Endpoint 生命周期基座（createEndpointLifecycle）
 

package/lib/adapter-index.d.ts

@@ -1,14 +1,17 @@
 import { generationAdmissionSource, type CapabilityId, type CapabilitySlot, type GenerationAdmissionGate, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import type { AdapterCapability, AdapterDefinition, AdapterSegmentPolicy, EndpointInstance, EndpointSendRequest } from './definition.js';
+import { type AdapterCapability, type AdapterDefinition, type AdapterOperation, type AdapterSegmentPolicy, type EndpointSendRequest } from './definition.js';
+import { type Endpoint } from './endpoint.js';
 import { type EndpointManagementCapability } from './endpoint-management.js';
+import { type EndpointControl } from './endpoint-control.js';
 import { type EndpointContentResolveContext } from './endpoint-content.js';
-import type { ConversationReference, ConversationResolution } from '@zhin.js/im-contract';
+import type { ConversationReference, ConversationResolution, EndpointCapabilities } from '@zhin.js/im-contract';
 export interface AdapterDescriptor {
     readonly id: CapabilityId;
     readonly owner: PluginId;
     readonly name: string;
     readonly source: string;
     readonly capabilities: readonly AdapterCapability[];
+    readonly operations: readonly AdapterOperation[];
 }
 /** Console / Host-facing endpoint row (connected = admission open). */
 export interface AdapterEndpointSummary extends AdapterDescriptor {
@@ -32,11 +35,21 @@ export declare class AdapterIndex {
      * Matches local name, capability id, or owner path segments.
      */
     resolve(adapter: string, endpointKey: string): CapabilityId | undefined;
-    /**
-     * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
-     */
-    instance(adapter: string, endpointKey: string): EndpointInstance | undefined;
+    /** Resolve the framework-owned Endpoint for internal Host control ports. */
+    connection(adapter: string, endpointKey: string): Endpoint | undefined;
+    /** Resolve the platform-native client owned by one active Endpoint. */
+    client<TClient>(adapter: string, endpointKey: string): TClient;
+    /** Resolve the Client directly from a generation-stable CapabilityId. */
+    clientById<TClient>(id: CapabilityId): TClient;
+    /** Literal adapter name used by authoring-context type discrimination. */
+    clientAdapter(id: CapabilityId): string;
+    /** Optional Client lookup for cross-platform middleware and routing. */
+    findClient<TClient>(adapter: string, endpointKey: string): TClient | undefined;
     owner(id: CapabilityId): PluginId;
+    /** Exact, serializable capabilities for one concrete Endpoint. */
+    capabilities(id: CapabilityId): EndpointCapabilities;
+    /** Returns the control port only when the concrete Endpoint declared the operation and is active. */
+    control(id: CapabilityId, operation: AdapterOperation): EndpointControl | undefined;
     /**
      * Endpoint 的消息段能力声明（出站协商降级依据）；
      * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。

package/lib/adapter-index.js

@@ -1,7 +1,9 @@
 import { DisposeStack, GenerationCompensationError, createGenerationAdmissionGate, generationAdmissionSource, } from '@zhin.js/plugin-runtime';
 import { createCapabilityContext } from '@zhin.js/feature-kit';
+import { endpointCapabilitiesOf, resolveAdapterOperations, } from './definition.js';
+import { bindEndpoint, isEndpoint } from './endpoint.js';
 import { listEndpointManagementCapabilities, } from './endpoint-management.js';
-import { assertDeclaredEndpointOperations } from './endpoint-control.js';
+import { assertDeclaredEndpointOperations, endpointControlOf, } from './endpoint-control.js';
 import { endpointContentOf } from './endpoint-content.js';
 export class AdapterIndex {
     $projection = 'zhin.adapter-index/1';
@@ -21,7 +23,7 @@ export class AdapterIndex {
             for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
                 signal.throwIfAborted();
                 for (const expansion of expandEndpointConfigs(slot, snapshot)) {
-                    const endpoint = await createEndpoint(slot, snapshot, admission, signal, expansion);
+                    const created = await createEndpoint(slot, snapshot, admission, signal, expansion);
                     signal.throwIfAborted();
                     records.push({
                         id: expansion.id,
@@ -31,7 +33,8 @@ export class AdapterIndex {
                         name: expansion.endpointId,
                         source: slot.source,
                         capabilities: slot.definition.capabilities,
-                        endpoint,
+                        operations: created.operations,
+                        endpoint: created.endpoint,
                         ...(slot.definition.segments ? { segments: slot.definition.segments } : {}),
                         started: false,
                         open: false,
@@ -59,6 +62,7 @@ export class AdapterIndex {
             name: endpointLiveName(record.endpoint) ?? record.name,
             source: record.source,
             capabilities: record.capabilities,
+            operations: record.operations,
             connected: record.open && !record.stopped,
             status: record.open && !record.stopped ? 'online' : 'offline',
             phase: endpointPhase(record),
@@ -79,21 +83,71 @@ export class AdapterIndex {
         const exact = matches.find((record) => record.name === endpointKey);
         return exact?.id ?? matches[0]?.id;
     }
-    /**
-     * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
-     */
-    instance(adapter, endpointKey) {
+    /** Resolve the framework-owned Endpoint for internal Host control ports. */
+    connection(adapter, endpointKey) {
         const id = this.resolve(adapter, endpointKey);
         if (!id)
             return undefined;
         return this.#records.get(id)?.endpoint;
     }
+    /** Resolve the platform-native client owned by one active Endpoint. */
+    client(adapter, endpointKey) {
+        const id = this.resolve(adapter, endpointKey);
+        const record = id ? this.#records.get(id) : undefined;
+        if (!record)
+            throw new Error(`Endpoint ${adapter}/${endpointKey} does not exist`);
+        if (!record.started || record.stopped) {
+            throw new Error(`Endpoint ${adapter}/${endpointKey} is not active`);
+        }
+        return record.endpoint.client;
+    }
+    /** Resolve the Client directly from a generation-stable CapabilityId. */
+    clientById(id) {
+        const record = this.#records.get(id);
+        if (!record)
+            throw new Error(`Unknown Adapter Endpoint: ${id}`);
+        if (!record.started || record.stopped) {
+            throw new Error(`Adapter Endpoint ${id} is not active`);
+        }
+        return record.endpoint.client;
+    }
+    /** Literal adapter name used by authoring-context type discrimination. */
+    clientAdapter(id) {
+        const record = this.#records.get(id);
+        if (!record)
+            throw new Error(`Unknown Adapter Endpoint: ${id}`);
+        return record.endpoint.identity.adapter;
+    }
+    /** Optional Client lookup for cross-platform middleware and routing. */
+    findClient(adapter, endpointKey) {
+        const id = this.resolve(adapter, endpointKey);
+        const record = id ? this.#records.get(id) : undefined;
+        if (!record || !record.started || record.stopped)
+            return undefined;
+        return record.endpoint.client;
+    }
     owner(id) {
         const record = this.#records.get(id);
         if (!record)
             throw new Error(`Unknown Adapter Endpoint: ${id}`);
         return record.owner;
     }
+    /** Exact, serializable capabilities for one concrete Endpoint. */
+    capabilities(id) {
+        const record = this.#records.get(id);
+        if (!record)
+            throw new Error(`Unknown Adapter Endpoint: ${id}`);
+        return endpointCapabilitiesOf(record, record.operations);
+    }
+    /** Returns the control port only when the concrete Endpoint declared the operation and is active. */
+    control(id, operation) {
+        const record = this.#records.get(id);
+        if (!record || !record.started || record.stopped)
+            return undefined;
+        if (!record.operations.includes(operation))
+            return undefined;
+        return endpointControlOf(record.endpoint);
+    }
     /**
      * Endpoint 的消息段能力声明（出站协商降级依据）；
      * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
@@ -130,6 +184,9 @@ export class AdapterIndex {
                 signal.throwIfAborted();
                 if (record.stopped)
                     throw new Error(`Adapter Endpoint stopped during start: ${record.id}`);
+                if (record.endpoint.client === record.endpoint) {
+                    throw new TypeError(`Adapter Endpoint ${record.id} must expose a distinct platform client`);
+                }
                 record.started = true;
             }
         }
@@ -230,7 +287,7 @@ function matchesEndpoint(record, adapter, endpointKey) {
         || record.id.endsWith(`/${adapter}`)
         || record.owner === adapter
         || record.owner.endsWith(`/${adapter}`);
-    // Live EndpointInstance.name is the bot runtime id (e.g. ICQQ uin). Host /
+    // The live Endpoint identity is the bot runtime id (e.g. ICQQ uin). Host /
     // activity-feedback resolve with that id; slot.localName alone is not enough
     // when multiple plugin instances share localName "icqq".
     const liveName = endpointLiveName(record.endpoint);
@@ -252,8 +309,8 @@ function endpointPhase(record) {
     return 'pending';
 }
 function assertEndpoint(value, id) {
-    if (!value || typeof value !== 'object') {
-        throw new TypeError(`Adapter ${id} create() must return an Endpoint instance`);
+    if (!isEndpoint(value)) {
+        throw new TypeError(`Adapter ${id} create() must return an Endpoint subclass`);
     }
 }
 /**
@@ -300,18 +357,21 @@ function expandEndpointConfigs(slot, snapshot) {
     })));
 }
 async function createEndpoint(slot, snapshot, admission, signal, expansion) {
-    const endpoint = await slot.definition.create(Object.freeze({
+    const context = Object.freeze({
         ...createCapabilityContext(snapshot, slot.owner, admission, signal),
         ...(expansion?.config ? { config: expansion.config } : {}),
         id: expansion?.id ?? slot.id,
         name: slot.localName,
-    }));
+    });
+    const operations = resolveAdapterOperations(slot.definition, context);
+    const endpoint = await slot.definition.create(context);
     assertEndpoint(endpoint, expansion?.id ?? slot.id);
+    bindEndpoint(endpoint, context, admission);
     if (slot.definition.capabilities.includes('outbound') && typeof endpoint.send !== 'function') {
         throw new TypeError(`Adapter Endpoint ${String(expansion?.id ?? slot.id)} declares outbound but send() is missing`);
     }
-    assertDeclaredEndpointOperations(endpoint, slot.definition.operations, String(expansion?.id ?? slot.id));
-    return endpoint;
+    assertDeclaredEndpointOperations(endpoint, operations, String(expansion?.id ?? slot.id));
+    return Object.freeze({ endpoint, operations });
 }
 async function stopRecords(records, primaryError) {
     const stack = new DisposeStack();

package/lib/definition.d.ts

@@ -1,13 +1,21 @@
+/**
+ * Adapter authoring API consumed from `zhin.js/adapter`.
+ * @module zhin.js/adapter
+ */
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import type { CapabilityContext } from '@zhin.js/feature-kit';
 import type { ConversationRef, EndpointCapabilities, EndpointOperation } from '@zhin.js/im-contract';
-import type { EndpointManagement } from './endpoint-management.js';
-import type { EndpointControl } from './endpoint-control.js';
-import type { EndpointContentPort } from './endpoint-content.js';
+import type { Endpoint } from './endpoint.js';
+export { Endpoint } from './endpoint.js';
+export type { EndpointEvent, EndpointIdentity, PlatformEvent, } from './endpoint.js';
+export { defineEndpointClient } from './endpoint-client.js';
+export type { EndpointClientContext, EndpointClientToken, } from './endpoint-client.js';
 declare const adapterBrand: "zhin.adapter/1";
 export type AdapterCapability = 'inbound' | 'outbound';
 /** Operations beyond sending, declared by an Adapter definition. */
 export type AdapterOperation = Exclude<EndpointOperation, 'send'>;
+/** Resolve operations for one concrete Endpoint configuration. */
+export type AdapterOperationDeclaration<TConfig = unknown> = readonly AdapterOperation[] | ((context: AdapterContext<TConfig>) => readonly AdapterOperation[]);
 /** 端点可消费的出站媒体来源形式。 */
 export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 /** 交互段（卡片/按钮等富交互）的端点消费方式。 */
@@ -19,24 +27,9 @@ export interface EndpointSendRequest {
     readonly conversation: ConversationRef;
     readonly payload: unknown;
 }
-export interface EndpointInstance {
-    /** Optional platform-neutral Console/Host management surface. */
-    readonly management?: EndpointManagement;
-    /** Optional platform-neutral control surface for existing messages. */
-    readonly control?: EndpointControl;
-    /** Optional canonical resolver for message, merged-forward and media references. */
-    readonly content?: EndpointContentPort;
-    /** Required readiness; must observe abort and settle before rollback returns. */
-    start?(signal: AbortSignal): void | Promise<void>;
-    /** Opens Endpoint-local flow behind the candidate generation admission gate. */
-    open?(): void;
-    /** Stops new inbound events while preserving in-flight work. */
-    close?(): void | Promise<void>;
-    /** Releases transport resources. Calls must be idempotent. */
-    stop?(): void | Promise<void>;
-    /** Platform message id. Core wraps it in the canonical MessageRef/DeliveryReceipt. */
-    send?(request: EndpointSendRequest): string | Promise<string>;
-}
+/**
+ * Generation-owned construction context for one runtime Endpoint.
+ */
 export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TConfig> {
     readonly id: CapabilityId;
     readonly name: string;
@@ -72,7 +65,8 @@ export interface AdapterSegmentPolicy {
     /** `native` preserves Markdown for the endpoint codec; `text` strips formatting in Core. */
     readonly markdown?: AdapterMarkdownMode;
 }
-export interface AdapterDefinition<TConfig = unknown> {
+export interface AdapterDefinition<TConfig = unknown, TClient = unknown> {
+    /** @internal Runtime feature brand. */
     readonly $feature: typeof adapterBrand;
     readonly capabilities: readonly AdapterCapability[];
     /**
@@ -80,18 +74,43 @@ export interface AdapterDefinition<TConfig = unknown> {
      * `capabilities: ['outbound']`; a method existing on an endpoint is not a
      * capability declaration.
      */
-    readonly operations?: readonly AdapterOperation[];
+    readonly operations?: AdapterOperationDeclaration<TConfig>;
     /** 可选：端点消息段能力声明（出站协商降级挂载点）。 */
     readonly segments?: AdapterSegmentPolicy;
-    create(context: AdapterContext<TConfig>): EndpointInstance | Promise<EndpointInstance>;
+    create(context: AdapterContext<TConfig>): Endpoint<TClient> | Promise<Endpoint<TClient>>;
 }
 declare module '@zhin.js/plugin-runtime' {
     interface PluginSetupContext<TConfig = unknown> {
         addAdapter(localName: string, definition: AdapterDefinition<TConfig>): void;
     }
 }
+/**
+ * Define an Adapter module for the `adapters/` convention directory.
+ *
+ * The returned definition is immutable and declares capabilities before an
+ * Endpoint is created, so Runtime admission can fail closed.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { defineAdapter } from 'zhin.js/adapter';
+ *
+ * export default defineAdapter({
+ *   capabilities: ['inbound', 'outbound'],
+ *   create: () => new MyPlatformEndpoint(),
+ * });
+ * ```
+ */
 export declare function defineAdapter<TConfig = unknown>(definition: Omit<AdapterDefinition<TConfig>, '$feature'>): Readonly<AdapterDefinition<TConfig>>;
-/** Converts the definition's compact authoring form into the public contract. */
-export declare function endpointCapabilitiesOf(definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>): EndpointCapabilities;
+/**
+ * Converts the definition's compact authoring form into the Runtime contract.
+ * @internal Adapter projection helper.
+ */
+export declare function endpointCapabilitiesOf(definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>, resolvedOperations?: readonly AdapterOperation[]): EndpointCapabilities;
+/**
+ * Resolve and validate the operation declaration for one concrete Endpoint.
+ * @internal Adapter projection helper.
+ */
+export declare function resolveAdapterOperations<TConfig>(definition: Pick<AdapterDefinition<TConfig>, 'operations'>, context: AdapterContext<TConfig>): readonly AdapterOperation[];
+/** @internal Runtime validation for convention-discovered modules. */
 export declare function parseAdapterDefinition(value: unknown): AdapterDefinition;
-export {};

package/lib/definition.js

@@ -1,9 +1,28 @@
+export { Endpoint } from './endpoint.js';
+export { defineEndpointClient } from './endpoint-client.js';
 const adapterBrand = 'zhin.adapter/1';
 const HTML_OUTBOUND_MODES = ['direct', 'image', 'text'];
 const OUTBOUND_MEDIA_FORMS = [
     'url', 'path', 'base64', 'upload',
 ];
 const ADAPTER_OPERATIONS = ['recall', 'edit', 'reaction', 'typing'];
+/**
+ * Define an Adapter module for the `adapters/` convention directory.
+ *
+ * The returned definition is immutable and declares capabilities before an
+ * Endpoint is created, so Runtime admission can fail closed.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { defineAdapter } from 'zhin.js/adapter';
+ *
+ * export default defineAdapter({
+ *   capabilities: ['inbound', 'outbound'],
+ *   create: () => new MyPlatformEndpoint(),
+ * });
+ * ```
+ */
 export function defineAdapter(definition) {
     if (typeof definition.create !== 'function') {
         throw new TypeError('Adapter create must be a function');
@@ -14,7 +33,9 @@ export function defineAdapter(definition) {
         throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
     }
     const segments = normalizeSegmentPolicy(definition.segments);
-    const operations = normalizeOperations(definition.operations);
+    const operations = typeof definition.operations === 'function'
+        ? definition.operations
+        : normalizeOperations(definition.operations);
     return Object.freeze({
         ...definition,
         $feature: adapterBrand,
@@ -23,15 +44,34 @@ export function defineAdapter(definition) {
         ...(segments ? { segments } : {}),
     });
 }
-/** Converts the definition's compact authoring form into the public contract. */
-export function endpointCapabilitiesOf(definition) {
-    const operations = definition.operations?.reduce((result, operation) => ({ ...result, [operation]: true }), {});
+/**
+ * Converts the definition's compact authoring form into the Runtime contract.
+ * @internal Adapter projection helper.
+ */
+export function endpointCapabilitiesOf(definition, resolvedOperations) {
+    if (typeof definition.operations === 'function' && resolvedOperations === undefined) {
+        throw new TypeError('Dynamic Adapter operations must be resolved for one Endpoint');
+    }
+    const declared = resolvedOperations
+        ?? (Array.isArray(definition.operations) ? definition.operations : undefined);
+    const operations = declared?.reduce((result, operation) => ({ ...result, [operation]: true }), {});
     return Object.freeze({
         inbound: definition.capabilities.includes('inbound'),
         outbound: definition.capabilities.includes('outbound'),
         ...(operations && Object.keys(operations).length > 0 ? { operations: Object.freeze(operations) } : {}),
     });
 }
+/**
+ * Resolve and validate the operation declaration for one concrete Endpoint.
+ * @internal Adapter projection helper.
+ */
+export function resolveAdapterOperations(definition, context) {
+    const declaration = definition.operations;
+    const operations = typeof declaration === 'function'
+        ? declaration(context)
+        : declaration;
+    return normalizeOperations(operations) ?? Object.freeze([]);
+}
 function normalizeOperations(operations) {
     if (operations === undefined)
         return undefined;
@@ -81,6 +121,7 @@ function normalizeSegmentPolicy(policy) {
         ...(policy.markdown ? { markdown: policy.markdown } : {}),
     });
 }
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseAdapterDefinition(value) {
     if (!value || typeof value !== 'object')
         throw invalidAdapter();
@@ -93,7 +134,9 @@ export function parseAdapterDefinition(value) {
         throw invalidAdapter();
     // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
     normalizeSegmentPolicy(definition.segments);
-    normalizeOperations(definition.operations);
+    if (typeof definition.operations !== 'function') {
+        normalizeOperations(definition.operations);
+    }
     return definition;
 }
 function invalidAdapter() {

package/lib/endpoint-client.d.ts

@@ -0,0 +1,62 @@
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+import { Endpoint } from './endpoint.js';
+declare const endpointClientBrand: "zhin.endpoint-client/1";
+export type { AdapterClient, AdapterClientRegistry, AdapterClientTypes, AdapterEvents, RegisteredAdapterName, } from '@zhin.js/feature-kit';
+/** Convert an EventEmitter-style tuple map into the payload map used by handlers. */
+export type ClientEventPayloads<TEvents extends object> = {
+    readonly [K in keyof TEvents]: TEvents[K] extends readonly [infer TPayload, ...unknown[]] ? TPayload : never;
+};
+interface ClientEventSource {
+    on(name: string, listener: (payload: unknown) => void): unknown;
+    off(name: string, listener: (payload: unknown) => void): unknown;
+}
+/**
+ * Forward one Client's public event surface through the Endpoint boundary.
+ * The returned disposer is useful when a Client can outlive its Endpoint.
+ */
+export declare function forwardEndpointClientEvents(client: ClientEventSource, names: readonly string[], receive: (name: string, payload: unknown) => void): () => void;
+export type ClientEventSubscription = (receive: (name: string, payload: unknown) => void) => () => void;
+/**
+ * Deep Endpoint base for SDK/protocol Clients.
+ *
+ * It owns the open admission gate and the single Client-event → Endpoint-event
+ * bridge. Concrete Endpoints only own account transport and raw-event
+ * normalization; they do not repeat dispatch plumbing.
+ */
+export declare abstract class ClientEndpoint<TClient = unknown> extends Endpoint<TClient> {
+    #private;
+    open(): void;
+    close(): void;
+    protected get clientEventsOpen(): boolean;
+    protected bindClientEvents(subscribe: ClientEventSubscription, receive?: (name: string, payload: unknown) => void, onError?: (name: string, error: unknown) => void): void;
+    protected releaseClientEvents(): void;
+}
+/** Typed identity for one platform's native Client surface. */
+export interface EndpointClientToken<TClient, TEvents extends object = Record<string, unknown>> {
+    readonly $client: typeof endpointClientBrand;
+    readonly adapter: string;
+    /** @internal Type-only covariance anchor. */
+    readonly _client?: TClient;
+    /** @internal Type-only covariance anchor for native platform events. */
+    readonly _events?: TEvents;
+    /**
+     * Resolve the Client from an operation context. Current inbound operations
+     * infer their Endpoint; detached operations must provide `endpointKey`.
+     */
+    get(context: EndpointClientContext, endpointKey?: string): TClient;
+    /** Resolve when this operation belongs to the platform; otherwise return undefined. */
+    find(context: EndpointClientContext, endpointKey?: string): TClient | undefined;
+}
+/** Operation-scoped sources that can resolve an Endpoint Client. */
+export interface EndpointClientContext {
+    readonly project?: CapabilityContext['project'];
+    readonly message?: unknown;
+    readonly input?: unknown;
+    readonly endpoint?: string;
+    readonly origin?: unknown;
+    readonly conversation?: unknown;
+    readonly $client?: unknown;
+    readonly clientAdapter?: string;
+}
+/** Declare the native Client type exported by a platform adapter. */
+export declare function defineEndpointClient<TClient, TEvents extends object = Record<string, unknown>>(adapter: string): EndpointClientToken<TClient, TEvents>;