@zhin.js/adapter 1.1.11 → 1.2.1

package/src/adapter-index.ts

@@ -10,20 +10,31 @@ import {
   type RuntimeSnapshot,
 } from '@zhin.js/plugin-runtime';
 import { createCapabilityContext } from '@zhin.js/feature-kit';
-import type {
-  AdapterCapability,
-  AdapterDefinition,
-  AdapterSegmentPolicy,
-  EndpointInstance,
-  EndpointSendRequest,
+import {
+  endpointCapabilitiesOf,
+  resolveAdapterOperations,
+  type AdapterCapability,
+  type AdapterDefinition,
+  type AdapterOperation,
+  type AdapterSegmentPolicy,
+  type EndpointSendRequest,
 } from './definition.js';
+import { bindEndpoint, isEndpoint, type Endpoint } from './endpoint.js';
 import {
   listEndpointManagementCapabilities,
   type EndpointManagementCapability,
 } from './endpoint-management.js';
-import { assertDeclaredEndpointOperations } from './endpoint-control.js';
+import {
+  assertDeclaredEndpointOperations,
+  endpointControlOf,
+  type EndpointControl,
+} from './endpoint-control.js';
 import { endpointContentOf, 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;
@@ -31,6 +42,7 @@ export interface AdapterDescriptor {
   readonly name: string;
   readonly source: string;
   readonly capabilities: readonly AdapterCapability[];
+  readonly operations: readonly AdapterOperation[];
 }
 
 /** Console / Host-facing endpoint row (connected = admission open). */
@@ -45,7 +57,7 @@ export type AdapterEndpointPhase =
   'pending' | 'starting' | 'online';
 
 interface AdapterRecord extends AdapterDescriptor {
-  readonly endpoint: EndpointInstance;
+  readonly endpoint: Endpoint;
   readonly segments?: AdapterSegmentPolicy;
   started: boolean;
   open: boolean;
@@ -80,7 +92,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,
@@ -90,7 +102,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,
@@ -122,6 +135,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' as const : 'offline' as const,
       phase: endpointPhase(record),
@@ -143,21 +157,70 @@ export class AdapterIndex {
     return exact?.id ?? matches[0]?.id;
   }
 
-  /**
-   * 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 {
     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<TClient>(adapter: string, endpointKey: string): TClient {
+    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 as TClient;
+  }
+
+  /** Resolve the Client directly from a generation-stable CapabilityId. */
+  clientById<TClient>(id: CapabilityId): TClient {
+    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 as TClient;
+  }
+
+  /** Literal adapter name used by authoring-context type discrimination. */
+  clientAdapter(id: CapabilityId): string {
+    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<TClient>(adapter: string, endpointKey: string): TClient | undefined {
+    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 as TClient;
+  }
+
   owner(id: CapabilityId): PluginId {
     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: CapabilityId): EndpointCapabilities {
+    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: CapabilityId, operation: AdapterOperation): EndpointControl | undefined {
+    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（调用方按历史行为处理）。
@@ -199,6 +262,11 @@ 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;
       }
     } catch (error) {
@@ -306,7 +374,7 @@ function matchesEndpoint(
     || 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);
@@ -317,7 +385,7 @@ function matchesEndpoint(
   return adapterOk && endpointOk;
 }
 
-function endpointLiveName(endpoint: EndpointInstance): string | undefined {
+function endpointLiveName(endpoint: Endpoint): string | undefined {
   const name = (endpoint as { readonly name?: unknown }).name;
   return typeof name === 'string' && name.length > 0 ? name : undefined;
 }
@@ -328,9 +396,9 @@ function endpointPhase(record: AdapterRecord): AdapterEndpointPhase {
   return 'pending';
 }
 
-function assertEndpoint(value: unknown, id: CapabilityId): asserts value is EndpointInstance {
-  if (!value || typeof value !== 'object') {
-    throw new TypeError(`Adapter ${id} create() must return an Endpoint instance`);
+function assertEndpoint(value: unknown, id: CapabilityId): asserts value is Endpoint {
+  if (!isEndpoint(value)) {
+    throw new TypeError(`Adapter ${id} create() must return an Endpoint subclass`);
   }
 }
 
@@ -396,16 +464,17 @@ async function createEndpoint(
   admission: GenerationAdmissionGate,
   signal: AbortSignal,
   expansion?: EndpointExpansion,
-): Promise<EndpointInstance> {
-  const endpoint = await slot.definition.create(
-    Object.freeze({
-      ...createCapabilityContext(snapshot, slot.owner, admission, signal),
-      ...(expansion?.config ? { config: expansion.config } : {}),
-      id: expansion?.id ?? slot.id,
-      name: slot.localName,
-    }),
-  );
+): Promise<Readonly<{ endpoint: Endpoint; operations: readonly AdapterOperation[] }>> {
+  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`,
@@ -413,10 +482,10 @@ async function createEndpoint(
   }
   assertDeclaredEndpointOperations(
     endpoint,
-    slot.definition.operations,
+    operations,
     String(expansion?.id ?? slot.id),
   );
-  return endpoint;
+  return Object.freeze({ endpoint, operations });
 }
 
 async function stopRecords(

package/src/definition.ts

@@ -1,3 +1,7 @@
+/**
+ * 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 {
@@ -5,9 +9,19 @@ import type {
   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';
 
 const adapterBrand = 'zhin.adapter/1' as const;
 
@@ -16,6 +30,11 @@ 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';
 
@@ -30,25 +49,9 @@ export interface EndpointSendRequest {
   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;
@@ -95,7 +98,8 @@ const OUTBOUND_MEDIA_FORMS: readonly AdapterOutboundMedia[] = [
 
 const ADAPTER_OPERATIONS: readonly AdapterOperation[] = ['recall', 'edit', 'reaction', 'typing'];
 
-export interface AdapterDefinition<TConfig = unknown> {
+export interface AdapterDefinition<TConfig = unknown, TClient = unknown> {
+  /** @internal Runtime feature brand. */
   readonly $feature: typeof adapterBrand;
   readonly capabilities: readonly AdapterCapability[];
   /**
@@ -103,12 +107,12 @@ 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>;
+  ): Endpoint<TClient> | Promise<Endpoint<TClient>>;
 }
 
 declare module '@zhin.js/plugin-runtime' {
@@ -120,6 +124,23 @@ declare module '@zhin.js/plugin-runtime' {
   }
 }
 
+/**
+ * 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<TConfig = unknown>(
   definition: Omit<AdapterDefinition<TConfig>, '$feature'>,
 ): Readonly<AdapterDefinition<TConfig>> {
@@ -134,7 +155,9 @@ export function defineAdapter<TConfig = unknown>(
     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,
@@ -144,11 +167,20 @@ export function defineAdapter<TConfig = unknown>(
   });
 }
 
-/** 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: Pick<AdapterDefinition, 'capabilities' | 'operations'>,
+  resolvedOperations?: readonly AdapterOperation[],
 ): EndpointCapabilities {
-  const operations = definition.operations?.reduce<Partial<Record<AdapterOperation, true>>>(
+  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<Partial<Record<AdapterOperation, true>>>(
     (result, operation) => ({ ...result, [operation]: true }),
     {},
   );
@@ -159,6 +191,21 @@ export function endpointCapabilitiesOf(
   });
 }
 
+/**
+ * Resolve and validate the operation declaration for one concrete Endpoint.
+ * @internal Adapter projection helper.
+ */
+export function resolveAdapterOperations<TConfig>(
+  definition: Pick<AdapterDefinition<TConfig>, 'operations'>,
+  context: AdapterContext<TConfig>,
+): readonly AdapterOperation[] {
+  const declaration = definition.operations;
+  const operations = typeof declaration === 'function'
+    ? declaration(context)
+    : declaration;
+  return normalizeOperations(operations) ?? Object.freeze([]);
+}
+
 function normalizeOperations(
   operations: readonly AdapterOperation[] | undefined,
 ): readonly AdapterOperation[] | undefined {
@@ -226,6 +273,7 @@ function normalizeSegmentPolicy(
   });
 }
 
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseAdapterDefinition(value: unknown): AdapterDefinition {
   if (!value || typeof value !== 'object') throw invalidAdapter();
   const definition = value as Partial<AdapterDefinition>;
@@ -240,7 +288,9 @@ export function parseAdapterDefinition(value: unknown): AdapterDefinition {
   ) throw invalidAdapter();
   // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
   normalizeSegmentPolicy(definition.segments);
-  normalizeOperations(definition.operations);
+  if (typeof definition.operations !== 'function') {
+    normalizeOperations(definition.operations);
+  }
   return definition as AdapterDefinition;
 }
 

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