@zhin.js/adapter 1.2.0 → 1.2.1

package/README.md

@@ -22,6 +22,28 @@ 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
@@ -43,7 +65,7 @@ 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.
@@ -53,6 +75,30 @@ New adapters should provide `control` directly and declare matching
 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）
 
 WS/SSE 类端点的 start/stop/重连/心跳统一走 `createEndpointLifecycle`

package/lib/adapter-index.d.ts

@@ -1,5 +1,6 @@
 import { generationAdmissionSource, type CapabilityId, type CapabilitySlot, type GenerationAdmissionGate, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { type AdapterCapability, type AdapterDefinition, type AdapterOperation, type AdapterSegmentPolicy, type EndpointInstance, type 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';
@@ -34,10 +35,16 @@ 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;

package/lib/adapter-index.js

@@ -1,6 +1,7 @@
 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, endpointControlOf, } from './endpoint-control.js';
 import { endpointContentOf } from './endpoint-content.js';
@@ -82,15 +83,49 @@ 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)
@@ -149,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;
             }
         }
@@ -249,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);
@@ -271,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`);
     }
 }
 /**
@@ -328,6 +366,7 @@ async function createEndpoint(slot, snapshot, admission, signal, expansion) {
     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`);
     }

package/lib/definition.d.ts

@@ -1,9 +1,15 @@
+/**
+ * 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. */
@@ -21,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;
@@ -74,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[];
     /**
@@ -85,17 +77,40 @@ export interface AdapterDefinition<TConfig = unknown> {
     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. */
+/**
+ * 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. */
+/**
+ * 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');
@@ -25,7 +44,10 @@ export function defineAdapter(definition) {
         ...(segments ? { segments } : {}),
     });
 }
-/** Converts the definition's compact authoring form into the public contract. */
+/**
+ * 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');
@@ -39,7 +61,10 @@ export function endpointCapabilitiesOf(definition, resolvedOperations) {
         ...(operations && Object.keys(operations).length > 0 ? { operations: Object.freeze(operations) } : {}),
     });
 }
-/** Resolve and validate the operation declaration for one concrete Endpoint. */
+/**
+ * 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'
@@ -96,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();

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>;

package/lib/endpoint-client.js

@@ -0,0 +1,163 @@
+import { isAdapterIndex } from './adapter-index.js';
+import { Endpoint } from './endpoint.js';
+import { adapterFeatureId } from './provider.js';
+const endpointClientBrand = 'zhin.endpoint-client/1';
+/**
+ * Forward one Client's public event surface through the Endpoint boundary.
+ * The returned disposer is useful when a Client can outlive its Endpoint.
+ */
+export function forwardEndpointClientEvents(client, names, receive) {
+    const subscriptions = names.map((name) => {
+        const listener = (payload) => receive(name, payload);
+        client.on(name, listener);
+        return { name, listener };
+    });
+    return () => {
+        for (const { name, listener } of subscriptions)
+            client.off(name, listener);
+    };
+}
+/**
+ * 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 class ClientEndpoint extends Endpoint {
+    #clientEventsOpen = false;
+    #clientEventsRelease;
+    open() {
+        this.#clientEventsOpen = true;
+    }
+    close() {
+        this.#clientEventsOpen = false;
+    }
+    get clientEventsOpen() {
+        return this.#clientEventsOpen;
+    }
+    bindClientEvents(subscribe, receive, onError) {
+        this.#clientEventsRelease?.();
+        this.#clientEventsRelease = subscribe((name, payload) => {
+            if (!this.#clientEventsOpen)
+                return;
+            void this.emitPlatform(name, payload).catch((error) => onError?.(name, error));
+            try {
+                receive?.(name, payload);
+            }
+            catch (error) {
+                onError?.(name, error);
+            }
+        });
+    }
+    releaseClientEvents() {
+        this.#clientEventsRelease?.();
+        this.#clientEventsRelease = undefined;
+    }
+}
+/** Declare the native Client type exported by a platform adapter. */
+export function defineEndpointClient(adapter) {
+    const normalized = adapter.trim();
+    if (!normalized)
+        throw new TypeError('Endpoint Client adapter cannot be empty');
+    const token = {
+        $client: endpointClientBrand,
+        adapter: normalized,
+        get(context, endpointKey) {
+            return resolveEndpointClient(context, token, endpointKey);
+        },
+        find(context, endpointKey) {
+            return findEndpointClient(context, token, endpointKey);
+        },
+    };
+    return Object.freeze(token);
+}
+/**
+ * Resolve a platform Client from the current generation.
+ *
+ * The returned object is valid only for the lifetime of `context`; callers
+ * must not retain it beyond the current command, handler, tool, task, or
+ * schedule operation.
+ */
+function resolveEndpointClient(context, token, endpointKey) {
+    if (token.$client !== endpointClientBrand) {
+        throw new TypeError('Invalid Endpoint Client token');
+    }
+    const current = currentClientSource(context);
+    if (current && '$client' in current) {
+        if (endpointKey && !matchesCurrentEndpoint(current, endpointKey)) {
+            throw new Error(`Endpoint Client ${endpointKey} does not match the current operation Endpoint`);
+        }
+        if (current.clientAdapter && current.clientAdapter !== token.adapter) {
+            throw new Error(`Endpoint Client ${token.adapter} cannot access ${current.clientAdapter}`);
+        }
+        return current.$client;
+    }
+    const resolvedEndpointKey = endpointKey ?? endpointKeyFromContext(context);
+    if (!resolvedEndpointKey) {
+        throw new Error('Detached Endpoint Client access requires an explicit endpoint key');
+    }
+    if (!context.project) {
+        throw new Error('Endpoint Client access requires a generation operation context');
+    }
+    const projection = context.project(adapterFeatureId);
+    if (!isAdapterIndex(projection)) {
+        throw new Error('Adapter Feature projection is not installed');
+    }
+    return projection.client(token.adapter, resolvedEndpointKey);
+}
+function findEndpointClient(context, token, endpointKey) {
+    const current = currentClientSource(context);
+    if (current && '$client' in current) {
+        if (current.clientAdapter && current.clientAdapter !== token.adapter)
+            return undefined;
+        if (endpointKey && !matchesCurrentEndpoint(current, endpointKey))
+            return undefined;
+        try {
+            return current.$client;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const resolvedEndpointKey = endpointKey ?? endpointKeyFromContext(context);
+    if (!resolvedEndpointKey || !context.project)
+        return undefined;
+    const projection = context.project(adapterFeatureId);
+    if (!isAdapterIndex(projection))
+        return undefined;
+    return projection.findClient(token.adapter, resolvedEndpointKey);
+}
+function currentClientSource(context) {
+    for (const candidate of [context, context.message, context.input]) {
+        if (candidate && typeof candidate === 'object'
+            && ('$client' in candidate || 'clientAdapter' in candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function matchesCurrentEndpoint(source, endpointKey) {
+    const candidates = [source.endpointId, conversationEndpointId(source.conversation)]
+        .filter((value) => typeof value === 'string' && value.length > 0);
+    return candidates.length === 0 || candidates.includes(endpointKey);
+}
+function endpointKeyFromContext(context) {
+    if (typeof context.endpoint === 'string' && context.endpoint.length > 0)
+        return context.endpoint;
+    const origin = context.origin;
+    if (origin?.kind === 'im' && typeof origin.endpoint === 'string' && origin.endpoint.length > 0) {
+        return origin.endpoint;
+    }
+    return conversationEndpointId(context.conversation)
+        ?? conversationEndpointId(context.input?.conversation);
+}
+function conversationEndpointId(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const endpoint = value.endpoint;
+    if (!endpoint || typeof endpoint !== 'object')
+        return undefined;
+    const id = endpoint.id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}

package/lib/endpoint-control.d.ts

@@ -2,7 +2,7 @@ import type { ConversationRef, MessageRef } from '@zhin.js/im-contract';
 /**
  * Transport-neutral control plane for a live endpoint.
  *
- * Sending belongs to EndpointInstance.send(). This port intentionally owns
+ * Sending belongs to Endpoint.send(). This port intentionally owns
  * operations that address an existing platform message, so Core never needs
  * to know a protocol's method names or identifier layout.
  */

package/lib/endpoint-lifecycle.js

@@ -22,25 +22,19 @@
  *    构造器里 `this.#lifecycle = createEndpointLifecycle({ name: config.id, reconnect, heartbeat })`。
  * 2. `start()` 改为：
  *    ```ts
- *    this.#unregisterAgent = registerXxxAgentEndpoint(name, this); // agent 注册仍在适配器侧
- *    try {
- *      await this.#lifecycle.start(async (handle) => {
- *        this.#handle = handle; // 供 ws 'close' 回调引用
- *        await new Promise<void>((resolve, reject) => {
- *          const ws = createWebSocket(...); this.#ws = ws;
- *          ws.on('open', () => { this.#lifecycle.startHeartbeat(() => beat(), interval); resolve(); });
- *          ws.on('close', (code, reason) => { handle.notifyClosed(...); rejectIfNotSettled(...); });
- *          ws.on('error', (err) => rejectIfNotSettled(err));
- *        });
+ *    await this.#lifecycle.start(async (handle) => {
+ *      this.#handle = handle; // 供 ws 'close' 回调引用
+ *      await new Promise<void>((resolve, reject) => {
+ *        const ws = createWebSocket(...); this.#ws = ws;
+ *        ws.on('open', () => { this.#lifecycle.startHeartbeat(() => beat(), interval); resolve(); });
+ *        ws.on('close', (code, reason) => { handle.notifyClosed(...); rejectIfNotSettled(...); });
+ *        ws.on('error', (err) => rejectIfNotSettled(err));
  *      });
- *    } catch (err) {
- *      this.#unregisterAgent?.(); this.#unregisterAgent = undefined; // 反注册对称
- *      throw err;
- *    }
+ *    });
  *    ```
- *    start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，刻意不收入基座。
+ *    start 失败复位由基座保证；Client 由 Endpoint 直接持有，不建立旁路 registry。
  * 3. `stop()` 改为：先 `await this.#lifecycle.stop()`（清定时器 + 强关 ws + 竞态 settle），
- *    再做适配器专有清理（rejectAllPending、deduper.clear、agent 反注册）。
+ *    再做适配器专有清理（rejectAllPending、deduper.clear）。
  * 4. `handle.onForceClose(() => this.#ws?.close())` 在每次拿到新 socket 后注册，
  *    供心跳看门狗主动断开；ws 'message'/'pong' 回调里调 `notifyHeartbeatAck()` 喂狗。
  * 5. 退避参数由配置映射：reconnect_interval → initialIntervalMs，可按需覆盖