@zhin.js/adapter 1.1.11 → 1.2.1

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.
  */
@@ -19,9 +19,13 @@ export interface EndpointControl {
 export interface EndpointWithControl {
     readonly control?: EndpointControl;
 }
+/** Bridges the common platform `recall(messageId)` shape into canonical control. */
+export declare function createRecallEndpointControl(recallById: (messageId: string) => void | Promise<void>): Readonly<EndpointControl>;
 /** Reads the canonical control port without probing protocol-specific methods. */
 export declare function endpointControlOf(endpoint: unknown): EndpointControl | undefined;
 /** Checks only an Endpoint's explicit `control` port; protocol methods are never probed. */
 export declare function hasExplicitEndpointOperation(endpoint: unknown, operation: 'recall' | 'edit' | 'reaction' | 'typing'): boolean;
+/** Lists the semantic operations implemented by an Endpoint's explicit control port. */
+export declare function listExplicitEndpointOperations(endpoint: unknown): readonly ('recall' | 'edit' | 'reaction' | 'typing')[];
 /** Rejects a declaration that cannot be fulfilled by the explicit control port. */
 export declare function assertDeclaredEndpointOperations(endpoint: unknown, operations: readonly ('recall' | 'edit' | 'reaction' | 'typing')[] | undefined, id: string): void;

package/lib/endpoint-control.js

@@ -1,3 +1,9 @@
+/** Bridges the common platform `recall(messageId)` shape into canonical control. */
+export function createRecallEndpointControl(recallById) {
+    return Object.freeze({
+        recall: (message) => Promise.resolve(recallById(message.id)),
+    });
+}
 /** Reads the canonical control port without probing protocol-specific methods. */
 export function endpointControlOf(endpoint) {
     if (!endpoint || typeof endpoint !== 'object')
@@ -19,6 +25,25 @@ export function hasExplicitEndpointOperation(endpoint, operation) {
         case 'typing': return typeof control.typing === 'function';
     }
 }
+/** Lists the semantic operations implemented by an Endpoint's explicit control port. */
+export function listExplicitEndpointOperations(endpoint) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return Object.freeze([]);
+    const control = endpoint.control;
+    if (!control || typeof control !== 'object')
+        return Object.freeze([]);
+    const operations = [];
+    if (typeof control.recall === 'function')
+        operations.push('recall');
+    if (typeof control.edit === 'function')
+        operations.push('edit');
+    if (typeof control.addReaction === 'function'
+        || typeof control.removeReaction === 'function')
+        operations.push('reaction');
+    if (typeof control.typing === 'function')
+        operations.push('typing');
+    return Object.freeze(operations);
+}
 /** Rejects a declaration that cannot be fulfilled by the explicit control port. */
 export function assertDeclaredEndpointOperations(endpoint, operations, id) {
     for (const operation of operations ?? []) {
@@ -26,7 +51,19 @@ export function assertDeclaredEndpointOperations(endpoint, operations, id) {
             throw new TypeError(`Adapter Endpoint ${id} declares ${operation} but control.${controlMethodName(operation)} is missing`);
         }
     }
+    const declared = new Set(operations ?? []);
+    for (const operation of listExplicitEndpointOperations(endpoint)) {
+        if (!declared.has(operation)) {
+            throw new TypeError(`Adapter Endpoint ${id} exposes control.${explicitControlMethodName(endpoint, operation)} but does not declare ${operation}`);
+        }
+    }
 }
 function controlMethodName(operation) {
     return operation === 'reaction' ? 'addReaction' : operation;
 }
+function explicitControlMethodName(endpoint, operation) {
+    if (operation !== 'reaction')
+        return operation;
+    const control = endpoint.control;
+    return typeof control?.addReaction === 'function' ? 'addReaction' : 'removeReaction';
+}

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，可按需覆盖

package/lib/endpoint.d.ts

@@ -0,0 +1,78 @@
+import { type CapabilityId, type GenerationAdmissionGate } from '@zhin.js/plugin-runtime';
+import type { AdapterContext, EndpointSendRequest } from './definition.js';
+import type { EndpointManagement } from './endpoint-management.js';
+import type { EndpointControl } from './endpoint-control.js';
+import type { EndpointContentPort } from './endpoint-content.js';
+/** The one inbound event boundary shared by every platform Endpoint. */
+export interface EndpointEventGateway {
+    receive(event: EndpointEvent): Promise<unknown>;
+}
+/** Callback shape used by protocol normalizers which feed Endpoint.emit(). */
+export type EndpointEventEmitter = <TPayload>(name: string, payload: TPayload) => Promise<unknown>;
+/** Generation-bound gateway injected into Endpoint by AdapterIndex. */
+export declare const endpointEventGatewayToken: import("@zhin.js/plugin-runtime").Token<EndpointEventGateway>;
+/** Stable identity of the Endpoint which produced an event. */
+export interface EndpointIdentity {
+    readonly id: CapabilityId;
+    readonly adapter: string;
+}
+/**
+ * The single event context delivered from an Endpoint into Core and plugins.
+ * `client` is the actual platform SDK/protocol client owned by the Endpoint.
+ */
+export interface EndpointEvent<TPayload = unknown, TClient = unknown, TName extends string = string> {
+    readonly name: TName;
+    readonly payload: TPayload;
+    readonly endpoint: EndpointIdentity;
+    readonly client: TClient;
+}
+/** Lossless native event delivered before any optional canonical projection. */
+export interface PlatformEvent<TEvent = unknown, TName extends string = string> {
+    /** Native SDK/protocol event name, for example `guild_member_add`. */
+    readonly name: TName;
+    /** Native SDK/protocol payload without canonicalization. */
+    readonly event: TEvent;
+}
+declare const endpointBrand: unique symbol;
+declare const endpointBind: unique symbol;
+/**
+ * Deep platform boundary.
+ *
+ * Platform implementations inherit this class, expose the platform-native
+ * `client`, own account/transport lifecycle, and normalize every inbound SDK
+ * callback through `emit()`. Core owns dispatch, admission and plugin context.
+ */
+export declare abstract class Endpoint<TClient = unknown> {
+    #private;
+    readonly [endpointBrand] = true;
+    /**
+     * Platform SDK or protocol client exposed to plugin code.
+     * It must be a distinct object: Endpoint owns framework lifecycle, Client
+     * owns platform operations.
+     */
+    abstract readonly client: TClient;
+    readonly management?: EndpointManagement;
+    readonly control?: EndpointControl;
+    readonly content?: EndpointContentPort;
+    /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+    [endpointBind](context: AdapterContext, admission?: GenerationAdmissionGate): void;
+    /** The identity is available after AdapterDefinition.create returns. */
+    get identity(): EndpointIdentity;
+    /** The only legal platform-to-framework event ingress. */
+    protected emit<TPayload, TName extends string>(name: TName, payload: TPayload): Promise<unknown>;
+    /**
+     * Lossless native-event projection. Adapters call this before deriving
+     * message/notice/request/system events, including for unknown event kinds.
+     */
+    protected emitPlatform<TEvent, TName extends string>(name: TName, event: TEvent): Promise<unknown>;
+    abstract start(signal: AbortSignal): void | Promise<void>;
+    abstract open(): void;
+    abstract close(): void | Promise<void>;
+    abstract stop(): void | Promise<void>;
+    send?(_request: EndpointSendRequest): string | Promise<string>;
+}
+/** @internal AdapterIndex binding hook; deliberately not exported by name. */
+export declare function bindEndpoint(endpoint: Endpoint, context: AdapterContext, admission?: GenerationAdmissionGate): void;
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export declare function isEndpoint(value: unknown): value is Endpoint;
+export {};

package/lib/endpoint.js

@@ -0,0 +1,100 @@
+import { createToken, } from '@zhin.js/plugin-runtime';
+/** Generation-bound gateway injected into Endpoint by AdapterIndex. */
+export const endpointEventGatewayToken = createToken('zhin.adapter.endpoint-events');
+const endpointBrand = Symbol.for('zhin.adapter.endpoint/1');
+const endpointBind = Symbol.for('zhin.adapter.endpoint-bind/1');
+const PRE_ADMISSION_EVENT_LIMIT = 256;
+/**
+ * Deep platform boundary.
+ *
+ * Platform implementations inherit this class, expose the platform-native
+ * `client`, own account/transport lifecycle, and normalize every inbound SDK
+ * callback through `emit()`. Core owns dispatch, admission and plugin context.
+ */
+export class Endpoint {
+    [endpointBrand] = true;
+    management;
+    control;
+    content;
+    #identity;
+    #events;
+    #admissionState = 'unbound';
+    #pendingEvents = [];
+    /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+    [endpointBind](context, admission) {
+        if (this.#events)
+            throw new Error(`Endpoint ${context.id} is already bound`);
+        this.#identity = Object.freeze({ id: context.id, adapter: context.name });
+        this.#events = context.use(endpointEventGatewayToken);
+        if (!admission) {
+            this.#admissionState = 'active';
+            return;
+        }
+        this.#admissionState = 'pending';
+        admission.onActivate(() => {
+            if (this.#admissionState !== 'pending')
+                return;
+            this.#admissionState = 'active';
+            admission.onDeactivate(() => {
+                this.#admissionState = 'retired';
+                this.#pendingEvents.length = 0;
+            });
+            const pending = this.#pendingEvents.splice(0);
+            for (const event of pending) {
+                void this.#events?.receive(event).catch(() => undefined);
+            }
+        });
+    }
+    /** The identity is available after AdapterDefinition.create returns. */
+    get identity() {
+        if (!this.#identity)
+            throw new Error('Endpoint is not bound to a runtime generation');
+        return this.#identity;
+    }
+    /** The only legal platform-to-framework event ingress. */
+    emit(name, payload) {
+        if (!this.#events || !this.#identity) {
+            throw new Error('Endpoint emitted before it was bound to a runtime generation');
+        }
+        const event = Object.freeze({
+            name,
+            payload,
+            endpoint: this.#identity,
+            client: this.client,
+        });
+        if (this.#admissionState === 'pending') {
+            if (this.#pendingEvents.length >= PRE_ADMISSION_EVENT_LIMIT) {
+                this.#pendingEvents.shift();
+            }
+            this.#pendingEvents.push(event);
+            return Promise.resolve(undefined);
+        }
+        if (this.#admissionState === 'retired')
+            return Promise.resolve(undefined);
+        return this.#events.receive(event);
+    }
+    /**
+     * Lossless native-event projection. Adapters call this before deriving
+     * message/notice/request/system events, including for unknown event kinds.
+     */
+    emitPlatform(name, event) {
+        return this.emit('platform.receive', Object.freeze({ name, event }));
+    }
+}
+/** @internal AdapterIndex binding hook; deliberately not exported by name. */
+export function bindEndpoint(endpoint, context, admission) {
+    endpoint[endpointBind](context, admission);
+}
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export function isEndpoint(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return candidate[endpointBrand] === true
+        && typeof candidate[endpointBind] === 'function'
+        && typeof candidate.start === 'function'
+        && typeof candidate.open === 'function'
+        && typeof candidate.close === 'function'
+        && typeof candidate.stop === 'function'
+        && 'client' in candidate;
+}

package/lib/index.d.ts

@@ -1,12 +1,18 @@
+/**
+ * Adapter authoring contracts and platform-neutral Endpoint capabilities.
+ * @module @zhin.js/adapter
+ */
 /** @internal 适配器 projection（AdapterIndex），框架内部机制，不承诺不 break。 */
 export * from './adapter-index.js';
 export * from './credentials.js';
 /** @public 用户侧创作面：`defineAdapter`（`adapters/` 约定目录默认导出，承诺 semver）。 */
 export * from './definition.js';
+export * from './endpoint.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
 export * from './endpoint-control.js';
 export * from './endpoint-content.js';
+export * from './endpoint-client.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -1,12 +1,18 @@
+/**
+ * Adapter authoring contracts and platform-neutral Endpoint capabilities.
+ * @module @zhin.js/adapter
+ */
 /** @internal 适配器 projection（AdapterIndex），框架内部机制，不承诺不 break。 */
 export * from './adapter-index.js';
 export * from './credentials.js';
 /** @public 用户侧创作面：`defineAdapter`（`adapters/` 约定目录默认导出，承诺 semver）。 */
 export * from './definition.js';
+export * from './endpoint.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
 export * from './endpoint-control.js';
 export * from './endpoint-content.js';
+export * from './endpoint-client.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/provider.d.ts

@@ -1,5 +1,5 @@
 import { AdapterIndex } from './adapter-index.js';
 export declare const adapterFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
-declare const adapterFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AdapterDefinition<unknown>, AdapterIndex>>;
+declare const adapterFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AdapterDefinition<unknown, unknown>, AdapterIndex>>;
 export { adapterFeature };
 export default adapterFeature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.1.11",
+  "version": "1.2.1",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,15 +18,15 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
+    "@zhin.js/feature-kit": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/feature-kit": "1.0.12",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/plugin-runtime": "1.1.7"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/plugin-runtime": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/command": "1.0.15"
+    "@zhin.js/command": "1.0.16"
   },
   "zhin": {
     "protocol": 1,