@zhin.js/adapter 1.2.0 → 1.2.1

package/src/endpoint-client.ts

@@ -0,0 +1,250 @@
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+import { isAdapterIndex } from './adapter-index.js';
+import { Endpoint } from './endpoint.js';
+import { adapterFeatureId } from './provider.js';
+
+const endpointClientBrand = 'zhin.endpoint-client/1' as const;
+
+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 function forwardEndpointClientEvents(
+  client: ClientEventSource,
+  names: readonly string[],
+  receive: (name: string, payload: unknown) => void,
+): () => void {
+  const subscriptions = names.map((name) => {
+    const listener = (payload: unknown) => receive(name, payload);
+    client.on(name, listener);
+    return { name, listener };
+  });
+  return () => {
+    for (const { name, listener } of subscriptions) client.off(name, listener);
+  };
+}
+
+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 abstract class ClientEndpoint<TClient = unknown> extends Endpoint<TClient> {
+  #clientEventsOpen = false;
+  #clientEventsRelease?: () => void;
+
+  open(): void {
+    this.#clientEventsOpen = true;
+  }
+
+  close(): void {
+    this.#clientEventsOpen = false;
+  }
+
+  protected get clientEventsOpen(): boolean {
+    return this.#clientEventsOpen;
+  }
+
+  protected bindClientEvents(
+    subscribe: ClientEventSubscription,
+    receive?: (name: string, payload: unknown) => void,
+    onError?: (name: string, error: unknown) => void,
+  ): void {
+    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);
+      }
+    });
+  }
+
+  protected releaseClientEvents(): void {
+    this.#clientEventsRelease?.();
+    this.#clientEventsRelease = undefined;
+  }
+}
+
+/** 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 function defineEndpointClient<
+  TClient,
+  TEvents extends object = Record<string, unknown>,
+>(adapter: string): EndpointClientToken<TClient, TEvents> {
+  const normalized = adapter.trim();
+  if (!normalized) throw new TypeError('Endpoint Client adapter cannot be empty');
+  const token: EndpointClientToken<TClient, TEvents> = {
+    $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<TClient, TEvents extends object>(
+  context: EndpointClientContext,
+  token: EndpointClientToken<TClient, TEvents>,
+  endpointKey?: string,
+): TClient {
+  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 as TClient;
+  }
+  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<unknown>(adapterFeatureId);
+  if (!isAdapterIndex(projection)) {
+    throw new Error('Adapter Feature projection is not installed');
+  }
+  return projection.client<TClient>(token.adapter, resolvedEndpointKey);
+}
+
+interface CurrentClientSource {
+  readonly endpointId?: string;
+  readonly clientAdapter?: string;
+  readonly conversation?: unknown;
+  readonly $client?: unknown;
+}
+
+function findEndpointClient<TClient, TEvents extends object>(
+  context: EndpointClientContext,
+  token: EndpointClientToken<TClient, TEvents>,
+  endpointKey?: string,
+): TClient | undefined {
+  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 as TClient;
+    } catch {
+      return undefined;
+    }
+  }
+  const resolvedEndpointKey = endpointKey ?? endpointKeyFromContext(context);
+  if (!resolvedEndpointKey || !context.project) return undefined;
+  const projection = context.project<unknown>(adapterFeatureId);
+  if (!isAdapterIndex(projection)) return undefined;
+  return projection.findClient<TClient>(token.adapter, resolvedEndpointKey);
+}
+
+function currentClientSource(context: EndpointClientContext): CurrentClientSource | undefined {
+  for (const candidate of [context, context.message, context.input]) {
+    if (candidate && typeof candidate === 'object'
+      && ('$client' in candidate || 'clientAdapter' in candidate)) {
+      return candidate as CurrentClientSource;
+    }
+  }
+  return undefined;
+}
+
+function matchesCurrentEndpoint(source: CurrentClientSource, endpointKey: string): boolean {
+  const candidates = [source.endpointId, conversationEndpointId(source.conversation)]
+    .filter((value): value is string => typeof value === 'string' && value.length > 0);
+  return candidates.length === 0 || candidates.includes(endpointKey);
+}
+
+function endpointKeyFromContext(context: EndpointClientContext): string | undefined {
+  if (typeof context.endpoint === 'string' && context.endpoint.length > 0) return context.endpoint;
+  const origin = context.origin as { readonly kind?: unknown; readonly endpoint?: unknown } | undefined;
+  if (origin?.kind === 'im' && typeof origin.endpoint === 'string' && origin.endpoint.length > 0) {
+    return origin.endpoint;
+  }
+  return conversationEndpointId(context.conversation)
+    ?? conversationEndpointId((context.input as { readonly conversation?: unknown } | undefined)?.conversation);
+}
+
+function conversationEndpointId(value: unknown): string | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const endpoint = (value as { readonly endpoint?: unknown }).endpoint;
+  if (!endpoint || typeof endpoint !== 'object') return undefined;
+  const id = (endpoint as { readonly id?: unknown }).id;
+  return typeof id === 'string' && id.length > 0 ? id : undefined;
+}

package/src/endpoint-control.ts

@@ -3,7 +3,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/src/endpoint-lifecycle.ts

@@ -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/src/endpoint.ts

@@ -0,0 +1,181 @@
+import {
+  createToken,
+  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 const endpointEventGatewayToken = createToken<EndpointEventGateway>(
+  'zhin.adapter.endpoint-events',
+);
+
+/** 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;
+}
+
+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 abstract class Endpoint<TClient = unknown> {
+  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;
+
+  #identity?: EndpointIdentity;
+  #events?: EndpointEventGateway;
+  #admissionState: 'unbound' | 'pending' | 'active' | 'retired' = 'unbound';
+  #pendingEvents: EndpointEvent[] = [];
+
+  /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+  [endpointBind](context: AdapterContext, admission?: GenerationAdmissionGate): void {
+    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(): EndpointIdentity {
+    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. */
+  protected emit<TPayload, TName extends string>(
+    name: TName,
+    payload: TPayload,
+  ): Promise<unknown> {
+    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.
+   */
+  protected emitPlatform<TEvent, TName extends string>(
+    name: TName,
+    event: TEvent,
+  ): Promise<unknown> {
+    return this.emit('platform.receive', Object.freeze({ name, event }));
+  }
+
+  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 function bindEndpoint(
+  endpoint: Endpoint,
+  context: AdapterContext,
+  admission?: GenerationAdmissionGate,
+): void {
+  endpoint[endpointBind](context, admission);
+}
+
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export function isEndpoint(value: unknown): value is Endpoint {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Partial<Endpoint> & {
+    readonly [endpointBrand]?: unknown;
+    readonly [endpointBind]?: unknown;
+  };
+  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/src/index.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';