@zhin.js/adapter-icqq 1.1.18 → 1.1.20

package/src/endpoint.ts

@@ -11,16 +11,29 @@ import {
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import {
-  Endpoint,
+  createEndpointSpecification,
+  endpointSpec,
+  type Endpoint,
+  type EndpointSpecification,
   type EndpointControl,
   type EndpointManagement,
   type EndpointPendingRequest,
   type EndpointSendRequest,
   type EndpointTransportState,
   type AdapterOutageNotifier,
+  createEndpointOperation,
+  type EndpointManagementRequest,
+  type EndpointGroupRequest,
+  type EndpointApproveRequest,
+  type EndpointRejectRequest,
+  type EndpointMemberRequest,
+  type EndpointMuteRequest,
+  type EndpointAdminRequest,
+  type EndpointUserRequest,
+  type EndpointGroupNoticeRequest,
 } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist, type PendingLoginTask } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist, type LoginAssistEndpointIdentity, type PendingLoginTask } from '@zhin.js/core';
 import { EndpointDeliveryError, type EndpointSendPart, type EndpointSendResult, type MessageRef } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -70,6 +83,8 @@ import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
   readonly config: ResolvedIcqqConfig;
+  readonly signal?: AbortSignal;
+  readonly endpointIdentity?: LoginAssistEndpointIdentity;
   readonly loginAssist: LoginAssist;
   readonly locale?: import('zhin.js/i18n').Locale;
   /** Out-of-band outage notifier; absent in tests/hosts without outbound. */
@@ -95,8 +110,8 @@ const BOUND_EVENTS = [
   'system.login.auth',
 ] as const;
 
-export class IcqqEndpoint extends Endpoint<Client> {
-  readonly client: ManagedIcqqClient;
+export class IcqqEndpoint extends ManagedIcqqClient implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
   readonly #logger: ReturnType<typeof getAdapterLogger>;
   readonly #options: IcqqEndpointOptions;
   readonly endpointName: string;
@@ -117,7 +132,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   readonly #inflightInbound = new Set<Promise<void>>();
   readonly #inboundOwner = new AsyncLocalStorage<symbol>();
   readonly #contentResolver: IcqqContentResolver;
-  readonly content: EndpointContentPort;
+  readonly #content: EndpointContentPort;
   readonly loginControl: IcqqLoginControl;
   #reloginTimer?: ReturnType<typeof setTimeout>;
   #reloginAttempts = 0;
@@ -125,67 +140,71 @@ export class IcqqEndpoint extends Endpoint<Client> {
   #offlineNoticeAt = 0;
   #challengeNoticeAt = 0;
 
-  readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
-    inspectGroupMember: (group, user, signal) => inspectGroupMember(this.client, group, user, signal),
-    inspectGroupScene: (group, signal) => inspectGroupScene(this.client, group, signal),
-    inspectGroupMemberProfile: (group, user, signal) => inspectGroupMemberProfile(this.client, group, user, signal),
-    moderateGroupMember: (group, user, action, signal) => moderateGroupMember(
-      this.client, group, user, action, signal, () => this.#open && !this.#retiring && !this.#stopped,
-    ),
-    listFriends: async () =>
-      Array.from(this.client.fl.values()).map((f) => ({
+  readonly #management: EndpointManagement = Object.freeze<EndpointManagement>({
+    inspectGroupMember: request => inspectGroupMember(this, request),
+    inspectGroupScene: request => inspectGroupScene(this, request),
+    inspectGroupMemberProfile: request => inspectGroupMemberProfile(this, request),
+    moderateGroupMember: request => moderateGroupMember({ client: this, isActive: () => this.#open && !this.#retiring && !this.#stopped }, request),
+    listFriends: async (request: EndpointManagementRequest = {}) =>
+      createEndpointOperation(request).run(() => Array.from(this.fl.values()).map((f) => ({
         user_id: f.user_id,
         nickname: f.nickname,
         remark: f.remark ?? '',
-      })),
-    listGroups: async () =>
-      Array.from(this.client.gl.values()).map((g) => ({
+      }))),
+    listGroups: async (request: EndpointManagementRequest = {}) =>
+      createEndpointOperation(request).run(() => Array.from(this.gl.values()).map((g) => ({
         group_id: g.group_id,
         name: g.group_name,
-      })),
-    listChannels: async () => {
-      await this.#guildCatalog.syncAll(this.client);
-      return this.#guildCatalog.getGuildChannelList();
+      }))),
+    listChannels: async (request: EndpointManagementRequest = {}) => {
+      const operation = createEndpointOperation(request);
+      await operation.run(() => this.#guildCatalog.syncAll(this));
+      return operation.run(() => this.#guildCatalog.getGuildChannelList());
     },
-    listGroupMembers: async (groupId) =>
-      Array.from((await this.client.getGroupMemberList(Number(groupId))).values()),
-    listRequests: () => this.#listPendingRequests(),
-    approveRequest: (requestId, remark) => this.#approveRequest(requestId, remark),
-    rejectRequest: (requestId, reason) => this.#rejectRequest(requestId, reason),
-    kickGroupMember: async (groupId, userId) => {
-      await this.client.setGroupKick(Number(groupId), Number(userId));
+    listGroupMembers: async ({ groupId, signal }: EndpointGroupRequest) =>
+      Array.from((await createEndpointOperation({ signal }).run(() => this.getGroupMemberList(Number(groupId)))).values()),
+    listRequests: (request: EndpointManagementRequest = {}) => createEndpointOperation(request).run(() => this.#listPendingRequests()),
+    approveRequest: request => this.#approveRequest(request),
+    rejectRequest: request => this.#rejectRequest(request),
+    kickGroupMember: async ({ groupId, userId, signal }: EndpointMemberRequest) => {
+      const operation = createEndpointOperation({ signal });
+      await operation.run(() => this.setGroupKick(Number(groupId), Number(userId)));
     },
-    muteGroupMember: async (groupId, userId, duration) => {
-      await this.client.setGroupBan(Number(groupId), Number(userId), duration);
+    muteGroupMember: async ({ groupId, userId, durationSeconds: duration, signal }: EndpointMuteRequest) => {
+      const operation = createEndpointOperation({ signal });
+      await operation.run(() => this.setGroupBan(Number(groupId), Number(userId), duration));
     },
-    setGroupAdmin: async (groupId, userId, enabled) => {
-      await this.client.setGroupAdmin(Number(groupId), Number(userId), enabled);
+    setGroupAdmin: async ({ groupId, userId, enabled, signal }: EndpointAdminRequest) => {
+      const operation = createEndpointOperation({ signal });
+      await operation.run(() => this.setGroupAdmin(Number(groupId), Number(userId), enabled));
     },
-    deleteFriend: async (userId) => {
-      await this.client.deleteFriend(Number(userId));
+    deleteFriend: async ({ userId, signal }: EndpointUserRequest) => {
+      const operation = createEndpointOperation({ signal });
+      await operation.run(() => this.deleteFriend(Number(userId)));
     },
-    sendGroupNotice: async (groupId, content) => {
-      if (await this.client.sendGroupNotice(Number(groupId), content) === false) {
+    sendGroupNotice: async ({ groupId, content, signal }: EndpointGroupNoticeRequest) => {
+      const operation = createEndpointOperation({ signal });
+      if (await operation.run(() => this.sendGroupNotice(Number(groupId), content)) === false) {
         throw new Error('QQ did not confirm the group notice');
       }
     },
   });
 
-  readonly control: EndpointControl = Object.freeze({
-    recall: async (message: MessageRef) => {
+  readonly #control: EndpointControl = Object.freeze<EndpointControl>({
+    recall: async ({ message, signal }) => {
       if (!message.id || message.id.startsWith('outbound:')) return;
-      if (!await this.client.deleteMsg(message.id)) throw new Error('QQ did not confirm message recall');
+      if (!await createEndpointOperation({ signal }).run(() => this.deleteMsg(message.id))) throw new Error('QQ did not confirm message recall');
     },
-    addReaction: async (message: MessageRef, emoji: string) => {
+    addReaction: async ({ message, emoji, signal }) => {
       const target = resolveIcqqGroupReactionTarget(message);
       if (!target) return null;
       try {
         // Do not await protocol ACK — packet timeout must not stall the AI reply.
-        this.#ignoreReactionAck(
-          'add',
-          this.client.pickGroup(target.groupId).setReaction(target.seq, emoji),
-        );
+        await createEndpointOperation({ signal }).run(() => {
+          this.#ignoreReactionAck('add', this.pickGroup(target.groupId).setReaction(target.seq, emoji));
+        });
       } catch (error) {
+        if (error instanceof EndpointDeliveryError && error.code === 'endpoint_inactive') throw error;
         this.#logger.debug(formatCompact({
           op: 'reaction_add_failed',
           error: error instanceof Error ? error.message : String(error),
@@ -193,15 +212,15 @@ export class IcqqEndpoint extends Endpoint<Client> {
       }
       return emoji;
     },
-    removeReaction: async (message: MessageRef, reactionId: string) => {
+    removeReaction: async ({ message, reactionId, signal }) => {
       const target = resolveIcqqGroupReactionTarget(message);
       if (!target) return;
       try {
-        this.#ignoreReactionAck(
-          'remove',
-          this.client.pickGroup(target.groupId).delReaction(target.seq, reactionId),
-        );
+        await createEndpointOperation({ signal }).run(() => {
+          this.#ignoreReactionAck('remove', this.pickGroup(target.groupId).delReaction(target.seq, reactionId));
+        });
       } catch (error) {
+        if (error instanceof EndpointDeliveryError && error.code === 'endpoint_inactive') throw error;
         this.#logger.debug(formatCompact({
           op: 'reaction_remove_failed',
           error: error instanceof Error ? error.message : String(error),
@@ -211,12 +230,20 @@ export class IcqqEndpoint extends Endpoint<Client> {
   });
 
   constructor(options: IcqqEndpointOptions) {
-    super();
-    const nativeConfig = resolveNativeClientConfig(options.config);
-    this.client = new ManagedIcqqClient(Number(options.config.id), nativeConfig,
+    super(Number(options.config.id), resolveNativeClientConfig(options.config),
       (operation, error) => this.#handleBackgroundFailure(operation, error));
-    this.#contentResolver = new IcqqContentResolver(this.client);
-    this.content = this.#contentResolver.port;
+    const name = () => this.endpointName;
+    const state = () => this.#transportState;
+    const content = () => this.#content;
+    this[endpointSpec] = createEndpointSpecification(this, {
+      start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(), stop: () => this.#stopFramework(),
+      send: request => this.#sendFramework(request), get name() { return name(); },
+      get transportState() { return state(); },
+      management: this.#management, control: this.#control,
+      get content() { return content(); },
+    });
+    this.#contentResolver = new IcqqContentResolver(this);
+    this.#content = this.#contentResolver.port;
     this.#logger = getAdapterLogger('icqq', options.config.id);
     this.#options = options;
     this.endpointName = options.config.id;
@@ -224,14 +251,14 @@ export class IcqqEndpoint extends Endpoint<Client> {
       endpointId: this.endpointName,
       state: () => ({
         endpointId: this.endpointName,
-        transportState: this.transportState,
-        online: this.client.isOnline(),
+        transportState: this.#transportState,
+        online: this.isOnline(),
         pending: this.#pendingLoginTasks(),
       }),
       pending: () => this.#pendingLoginTasks(),
-      relogin: () => this.relogin(),
-      submit: (taskId: string, value: string | Record<string, unknown>) => this.#options.loginAssist.submit(taskId, value),
-      cancel: (taskId: string, reason?: string) => this.#options.loginAssist.cancel(taskId, reason),
+      relogin: async () => { this.#options.signal?.throwIfAborted(); await this.relogin(); },
+      submit: (taskId: string, value: string | Record<string, unknown>) => !this.#options.signal?.aborted && this.#options.loginAssist.submit(taskId, value, this.#options.endpointIdentity),
+      cancel: (taskId: string, reason?: string) => !this.#options.signal?.aborted && this.#options.loginAssist.cancel(taskId, reason, this.#options.endpointIdentity),
     });
   }
 
@@ -244,11 +271,11 @@ export class IcqqEndpoint extends Endpoint<Client> {
         : typeof error === 'string' ? error : 'Unknown ICQQ SDK background failure',
       ...(error && typeof error === 'object' && 'code' in error && typeof error.code === 'number' ? { code: error.code } : {}),
     }));
-    if (operation === 'sso-heartbeat' && !this.client.isOnline()) return;
+    if (operation === 'sso-heartbeat' && !this.isOnline()) return;
     if (operation === 'login' && !this.#everOnline) return;
     // Delegate to the SDK's existing transport termination, offline event and
     // reconn_interval policy. No account-level logout or second retry timer.
-    this.client.emit('internal.error.network', -2, `ICQQ ${operation} failed`);
+    this.emit('internal.error.network', -2, `ICQQ ${operation} failed`);
   }
 
   /** Force a login attempt (manual recovery command). */
@@ -266,7 +293,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     this.#reloginInFlight = task;
     void task.catch(() => undefined).finally(() => {
       if (this.#reloginInFlight === task) this.#reloginInFlight = undefined;
-      if (this.#started && !this.#stopped && !this.#retiring && !this.client.isOnline()) {
+      if (this.#started && !this.#stopped && !this.#retiring && !this.isOnline()) {
         this.#scheduleRelogin('relogin_failed');
       }
     });
@@ -275,10 +302,10 @@ export class IcqqEndpoint extends Endpoint<Client> {
 
   async #performRelogin(): Promise<void> {
     this.#clearReloginTimer();
-    this.client.cancelReconnect();
+    this.cancelReconnect();
     this.#logger.info(formatCompact({ op: 'icqq_relogin', endpoint: this.endpointName }));
     try {
-      await this.client.login(this.#options.config.password);
+      await this.login(this.#options.config.password);
     } catch (error) {
       this.#logger.warn(formatCompact({
         op: 'icqq_relogin_failed',
@@ -318,8 +345,14 @@ export class IcqqEndpoint extends Endpoint<Client> {
   }
 
   #pendingLoginTasks(): readonly PendingLoginTask[] {
+    if (this.#options.signal?.aborted) return [];
     return this.#options.loginAssist.listPending()
-      .filter((task) => task.adapter === 'icqq' && task.endpointKey === this.endpointName);
+      .filter((task) => task.adapter === 'icqq' && (this.#options.endpointIdentity
+        ? task.endpointIdentity?.canonicalId === this.#options.endpointIdentity.canonicalId
+          && task.endpointIdentity.instanceId === this.#options.endpointIdentity.instanceId
+          && task.endpointIdentity.epoch === this.#options.endpointIdentity.epoch
+          && task.endpointIdentity.incarnationId === this.#options.endpointIdentity.incarnationId
+        : task.endpointKey === this.endpointName));
   }
 
   #notifyOffline(reason: string, willRetry: boolean): void {
@@ -395,15 +428,15 @@ export class IcqqEndpoint extends Endpoint<Client> {
     });
   }
 
-  get transportState(): EndpointTransportState {
+  get #transportState(): EndpointTransportState {
     if (this.#stopped || this.#retiring) return 'stopped';
     if (!this.#started) return 'idle';
-    if (this.client.isOnline()) return 'open';
+    if (this.isOnline()) return 'open';
     if (!this.#everOnline) return 'connecting';
     return this.#options.config.autoReconnect ? 'reconnecting' : 'closed';
   }
 
-  async start(signal: AbortSignal): Promise<void> {
+  async #startFramework(signal: AbortSignal): Promise<void> {
     if (this.#started) return;
     signal.throwIfAborted();
     this.#stopped = false;
@@ -412,7 +445,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     this.#retirementEpoch += 1;
     this.#retirementArmed = false;
     this.#retiring = false;
-    this.client.off('system.online');
+    this.off('system.online');
     this.#started = true;
     let resolveOnline!: () => void;
     const onlineReady = new Promise<void>((resolve) => {
@@ -423,17 +456,17 @@ export class IcqqEndpoint extends Endpoint<Client> {
     signal.addEventListener('abort', onAbort, { once: true });
     try {
       this.#bindClientEvents();
-      await raceAbort(Promise.resolve(this.client.login(this.#options.config.password)), signal);
+      await raceAbort(Promise.resolve(this.login(this.#options.config.password)), signal);
       await onlineReady;
       signal.throwIfAborted();
       await this.#pullPendingSystemMessages(signal);
       signal.throwIfAborted();
       this.#logger.info(
-        `connected (direct) | friends: ${this.client.fl.size} | groups: ${this.client.gl.size}`,
+        `connected (direct) | friends: ${this.fl.size} | groups: ${this.gl.size}`,
       );
     } catch (error) {
       this.#notifyOffline('start_failed', false);
-      await this.stop();
+      await this.#stopFramework();
       this.#logger.debug(`Failed to connect ICQQ client: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
       throw error;
     } finally {
@@ -442,11 +475,11 @@ export class IcqqEndpoint extends Endpoint<Client> {
     }
   }
 
-  open(): void {
+  #openFramework(): void {
     if (this.#retirementArmed) {
       this.#retirementEpoch += 1;
       this.#retirementArmed = false;
-      this.client.off('system.online');
+      this.off('system.online');
       this.#bindSystemOnlineEvent();
     }
     this.#retiring = false;
@@ -459,16 +492,16 @@ export class IcqqEndpoint extends Endpoint<Client> {
     }
   }
 
-  async close(): Promise<void> {
+  async #closeFramework(): Promise<void> {
     this.#assertExternalLifecycle('close');
     this.#armRetirementFence();
     await Promise.allSettled([...this.#inflightInbound]);
   }
 
-  async stop(): Promise<void> {
+  async #stopFramework(): Promise<void> {
+    this.#assertExternalLifecycle('stop');
     this.#stopped = true;
     this.#clearReloginTimer();
-    this.#assertExternalLifecycle('stop');
     this.#armRetirementFence();
     await Promise.allSettled([...this.#inflightInbound]);
     this.#resolveStartOnline?.();
@@ -479,7 +512,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     for (const event of BOUND_EVENTS) {
       // The retirement guard owns this matcher until a late login handshake
       // has finished. start()/open() replace it with the normal listener.
-      if (event !== 'system.online') this.client.off(event);
+      if (event !== 'system.online') this.off(event);
     }
     // `Client.logout()` sends an account-level unregister packet before it
     // closes this transport. During config HMR the replacement endpoint for
@@ -487,7 +520,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     // also closes the replacement session. Endpoint ownership is transport
     // scoped: retire only this Client's TCP connection.
     try {
-      this.client.terminate();
+      this.terminate();
     } catch { /* ignore */ }
       this.#inboundDeduper.clear();
       this.#sideEventDeduper.clear();
@@ -504,26 +537,37 @@ export class IcqqEndpoint extends Endpoint<Client> {
     const retirementEpoch = ++this.#retirementEpoch;
     // ICQQ owns reconnect through this per-Client timer. Clear it before any
     // asynchronous drain so a queued callback cannot enter while close waits.
-    this.client.cancelReconnect();
+    this.cancelReconnect();
     // A login callback may already be inside the SDK handshake, which has no
     // abort API. Replace the normal online listener with an epoch-owned guard
     // before draining inbound work. Transport termination is account-local;
     // logout would also unregister an HMR replacement using the same UIN.
-    this.client.off('system.online');
-    this.client.on('system.online', () => {
+    this.off('system.online');
+    this.on('system.online', () => {
       if (this.#retirementEpoch !== retirementEpoch || !this.#retiring) return;
       try {
-        this.client.terminate();
+        this.terminate();
       } catch { /* already closed */ }
     });
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<EndpointSendResult> {
+  async #sendFramework({ conversation, payload, signal }: EndpointSendRequest): Promise<EndpointSendResult> {
     if (!this.#started) throw new EndpointDeliveryError('endpoint_disconnected', 'icqq endpoint 未连接', 'not_sent');
+    const operation = createEndpointOperation({ signal });
     const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
-    const prepared = isIcqqSegmentPayload(payload)
+    const prepared = await operation.prepare(() => isIcqqSegmentPayload(payload)
       ? prepareIcqqOutboundMedia(normalizeIcqqImageMedia(payload), mediaMode)
-      : { content: payload, dispose() {} };
+      : { content: payload, dispose() {} });
+    // Cancellation ends our wait, not the SDK's use of temporary media. The actual native
+    // promises own that resource until they settle, including a late rejection after cancellation.
+    const pendingSends = new Set<Promise<{ message_id?: unknown }>>();
+    const sendNative = (target: ReturnType<typeof icqqOutboundTarget>, message: Sendable) => {
+      const task = this.#sendNative(target, message);
+      pendingSends.add(task);
+      const settled = () => { pendingSends.delete(task); };
+      void task.then(settled, settled);
+      return task;
+    };
     try {
       // Standalone elements (share / file / …) are split into ordered messages.
       const messages = formatOutboundMessageParts(prepared.content);
@@ -533,7 +577,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
         const preview = formatIcqqSendablePreview(message);
         let result: { message_id?: unknown };
         try {
-          result = await this.#sendNative(parsed, message);
+          result = await operation.run(() => sendNative(parsed, message));
         } catch (error) {
           this.#logger.warn(formatCompact({
             op: 'icqq_send_failed',
@@ -560,12 +604,14 @@ export class IcqqEndpoint extends Endpoint<Client> {
       }
       return { parts };
     } finally {
-      try {
-        prepared.dispose();
-      } catch (error) {
-        // Temporary-file cleanup cannot change an already observed platform send outcome.
-        this.#logger.warn(formatCompact({ op: 'icqq_media_cleanup_failed', error: describeUnknownError(error) }));
-      }
+      const disposeMedia = () => {
+        try { prepared.dispose(); } catch (error) {
+          // Temporary-file cleanup cannot change an observed send result.
+          this.#logger.warn(formatCompact({ op: 'icqq_media_cleanup_failed', error: describeUnknownError(error) }));
+        }
+      };
+      if (pendingSends.size) void Promise.allSettled([...pendingSends]).then(disposeMedia);
+      else disposeMedia();
     }
   }
 
@@ -576,20 +622,20 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (isIcqqShareElement(message)) {
       switch (target.kind) {
         case 'private': {
-          const friend = this.client.pickFriend(target.userId);
+          const friend = this.pickFriend(target.userId);
           await friend.share(message);
           return {};
         }
         case 'group': {
-          const group = this.client.pickGroup(target.groupId);
+          const group = this.pickGroup(target.groupId);
           await group.share(message);
           return {};
         }
         case 'temp':
-          await this.client.pickMember(target.groupId, target.userId).share(message);
+          await this.pickMember(target.groupId, target.userId).share(message);
           return {};
         case 'channel': {
-          const channel = this.client.pickGuild(target.guildId).channels.get(target.channelId);
+          const channel = this.pickGuild(target.guildId).channels.get(target.channelId);
           if (!channel) {
             throw new TypeError(`ICQQ guild channel is unavailable: ${target.guildId}/${target.channelId}`);
           }
@@ -601,11 +647,11 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (isIcqqFileElement(message)) {
       switch (target.kind) {
         case 'private': {
-          await this.client.pickFriend(target.userId).sendFile(message.file, message.name);
+          await this.pickFriend(target.userId).sendFile(message.file, message.name);
           return {};
         }
         case 'group': {
-          await this.client.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
+          await this.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
           return {};
         }
         case 'temp':
@@ -615,13 +661,13 @@ export class IcqqEndpoint extends Endpoint<Client> {
     }
     switch (target.kind) {
       case 'private':
-        return this.client.sendPrivateMsg(target.userId, message);
+        return this.sendPrivateMsg(target.userId, message);
       case 'group':
-        return this.client.sendGroupMsg(target.groupId, message);
+        return this.sendGroupMsg(target.groupId, message);
       case 'temp':
-        return this.client.sendTempMsg(target.groupId, target.userId, message);
+        return this.sendTempMsg(target.groupId, target.userId, message);
       case 'channel':
-        return this.client.sendGuildMsg(target.guildId, target.channelId, message) as unknown as { message_id?: unknown };
+        return this.sendGuildMsg(target.guildId, target.channelId, message) as unknown as { message_id?: unknown };
     }
   }
 
@@ -636,7 +682,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     this.#inflightInbound.add(settlement);
     let operation: Promise<void>;
     try {
-      operation = this.#inboundOwner.run(owner, run);
+      operation = this.#inboundOwner.run(owner, () => this[endpointSpec].events.run(run));
     } catch (error) {
       this.#inflightInbound.delete(settlement);
       settle();
@@ -690,7 +736,9 @@ export class IcqqEndpoint extends Endpoint<Client> {
       + (mentioned ? ' (mentioned)' : '')
       + ` | ${truncatePreview(msg.content, 80)}`,
     );
-    await this.emit('message.receive', {
+    await this[endpointSpec].events.emit('message.receive', {
+      event: msg.event,
+      platformSentAt: Number.isFinite(msg.platformSentAt) ? msg.platformSentAt : undefined,
       conversation,
       message: { conversation, id: msg.id },
       content: msg.content,
@@ -717,77 +765,70 @@ export class IcqqEndpoint extends Endpoint<Client> {
   #bindClientEvents(): void {
     this.#bindNativeEvents();
     const safe = (label: string, fn: () => void): void => {
-      try {
-        fn();
-      } catch (error) {
-        this.#logger.warn(formatCompact({
-          op: 'icqq_event_handler',
-          endpoint: this.endpointName,
-          event: label,
-          error: error instanceof Error ? error.message : String(error),
-        }));
-      }
+      void this[endpointSpec].events.run(fn).catch(() => {
+        this.#logger.debug(formatCompact({ op: 'icqq_event_not_admitted', endpoint: this.endpointName, event: label }));
+      });
     };
-    this.client.on('message.private', (event) => {
+    this.on('message.private', (event) => {
       this.#startMessageEvent('message.private', event);
     });
-    this.client.on('message.group', (event) => {
+    this.on('message.group', (event) => {
       this.#startMessageEvent('message.group', event);
     });
-    this.client.on('message.guild', (event) => {
-      void this.#handleGuildEvent(event).catch((error) => {
+    this.on('message.guild', (event) => {
+      void this.#trackInbound(() => this.#handleGuildEvent(event)).catch((error) => {
         this.#logInboundHandlerFailure('message.guild', error);
       });
     });
-    this.client.on('request.friend', (event) => safe('request.friend', () => {
+    this.on('request.friend', (event) => safe('request.friend', () => {
       this.#onRequestEvent(serializeIcqqEvent(event));
     }));
-    this.client.on('request.group', (event) => safe('request.group', () => {
+    this.on('request.group', (event) => safe('request.group', () => {
       this.#onRequestEvent(serializeIcqqEvent(event));
     }));
-    this.client.on('notice.friend', (event) => safe('notice.friend', () => {
+    this.on('notice.friend', (event) => safe('notice.friend', () => {
       this.#onNoticeEvent(serializeIcqqEvent(event));
     }));
-    this.client.on('notice.group', (event) => safe('notice.group', () => {
+    this.on('notice.group', (event) => safe('notice.group', () => {
       this.#onNoticeEvent(serializeIcqqEvent(event));
     }));
     this.#bindSystemOnlineEvent();
-    this.client.on('system.offline', (event) => {
+    this.on('system.offline', (event) => {
       this.#logSystemEvent('offline', event);
       this.#notifyOffline('offline', this.#options.config.autoReconnect);
     });
-    this.client.on('system.offline.network', (event) => {
+    this.on('system.offline.network', (event) => {
       this.#logSystemEvent('offline.network', event);
       this.#notifyOffline('network', this.#options.config.autoReconnect);
     });
-    this.client.on('system.offline.kickoff', (event) => {
+    this.on('system.offline.kickoff', (event) => {
       this.#logSystemEvent('offline.kickoff', event);
       this.#notifyOffline('kickoff', this.#options.config.autoReconnect);
       this.#scheduleRelogin('kickoff');
     });
-    this.client.on('system.login.qrcode', (event) => {
+    this.on('system.login.qrcode', (event) => {
       this.#logger.info('icqq 收到二维码登录事件，等待 LoginAssist / 终端确认后继续');
       this.#handleLoginChallenge('qrcode', event);
     });
-    this.client.on('system.login.device', (event) => {
+    this.on('system.login.device', (event) => {
       this.#handleLoginChallenge('device', event);
     });
-    this.client.on('system.login.slider', (event) => {
+    this.on('system.login.slider', (event) => {
       this.#handleLoginChallenge('slider', event);
     });
-    this.client.on('system.login.error', (event) => {
+    this.on('system.login.error', (event) => {
       this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'login_error');
       this.#logSystemEvent('login.error', event);
       this.#notifyOffline('login_error', this.#options.config.autoReconnect);
       this.#scheduleRelogin('login_error');
     });
-    this.client.on('system.login.auth', (event) => {
+    this.on('system.login.auth', (event) => {
       this.#handleLoginChallenge('auth', event);
     });
   }
 
   #bindSystemOnlineEvent(): void {
-    this.client.on('system.online', (event) => {
+    this.on('system.online', (event) => {
       if (this.#retiring) return;
       this.#everOnline = true;
       this.#clearReloginTimer();
@@ -798,7 +839,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
         this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
         try {
           // transport 重连不清除（账号不变）；stop/retire 由基类撤销登记。上报失败不影响上线流程。
-          this.reportSelfUserId(resolveIcqqSelfUserId(this.client));
+          this[endpointSpec].reportSelfUserId(resolveIcqqSelfUserId(this));
         } catch (error) {
           this.#logger.warn(formatCompact({
             op: 'icqq_report_self_user_id_failed',
@@ -822,7 +863,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   #bindNativeEvents(): void {
     this.#disposeNativeEvents?.();
     let matchedName: string | undefined;
-    const registration = this.client.on(
+    const registration = this.on(
       (eventName: unknown) => {
         matchedName = typeof eventName === 'string' && !eventName.startsWith('internal.')
           ? eventName
@@ -838,7 +879,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   }
 
   #emitNativeEvent(name: string, event: unknown): void {
-    void this.emitPlatform(name, event).catch((error) => {
+    void this[endpointSpec].events.platform(name, event).catch((error) => {
       this.#logger.warn(formatCompact({
         op: 'icqq_platform_event_failed',
         endpoint: this.endpointName,
@@ -852,6 +893,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     step: 'qrcode' | 'slider' | 'device' | 'auth',
     event: unknown,
   ): void {
+    if (this.#retiring || this.#stopped || this.#options.signal?.aborted) return;
     const payload = serializeIcqqEvent(event) ?? (event && typeof event === 'object'
       ? event as Record<string, unknown>
       : null);
@@ -861,10 +903,11 @@ export class IcqqEndpoint extends Endpoint<Client> {
     void runIcqqLoginAssistStep({
       assist: this.#options.loginAssist,
       locale: this.#options.locale,
-      client: this.client,
+      client: this,
       adapter: 'icqq',
       endpointKey: this.endpointName,
       owner: this.#loginAssistOwner,
+      signal: this.#options.signal, endpointIdentity: this.#options.endpointIdentity,
       logger: this.#logger,
       step,
       event: payload ?? event,
@@ -885,14 +928,14 @@ export class IcqqEndpoint extends Endpoint<Client> {
     const postType = String(payload.post_type ?? '');
     const isRequest = postType === 'request' || postType.startsWith('request.');
     const flag = payload.flag != null ? String(payload.flag) : '';
-    void receiveOneBotLikeSideEvent((name, payload) => this.emit(name, payload), {
+    void receiveOneBotLikeSideEvent((name, payload) => this[endpointSpec].events.emit(name, payload), {
       adapter: 'icqq',
       endpointKey: this.endpointName,
       platform: 'icqq',
       raw: payload,
       ...(isRequest ? {
-        approve: (id, remark) => this.#approveRequest(flag || id, remark),
-        reject: (id, reason) => this.#rejectRequest(flag || id, reason),
+        approve: (id, remark) => this.#approveRequest({ requestId: flag || id, remark }),
+        reject: (id, reason) => this.#rejectRequest({ requestId: flag || id, reason }),
       } : {}),
     }).catch((err) => {
       this.#logger.warn(formatCompact({
@@ -905,7 +948,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   }
 
   #dispatchIcqqSystemSideEvent(type: string, payload: Record<string, unknown> | null): void {
-    void this.emit('system.receive', buildSystem(payload ?? {}, {
+    void this[endpointSpec].events.emit('system.receive', buildSystem(payload ?? {}, {
       id: `system:${this.endpointName}:${type}:${Date.now()}`,
       clientAdapter: 'icqq',
       endpointId: this.endpointName,
@@ -998,6 +1041,8 @@ export class IcqqEndpoint extends Endpoint<Client> {
       }));
     }
     await this.#deliverInbound({
+      event,
+      platformSentAt: normalized.timestampMs,
       id: normalized.messageId,
       conversation,
       content: formatInboundContent(normalized.rawMessage),
@@ -1029,13 +1074,13 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (!Number.isFinite(userId) || userId <= 0) return null;
     if (data.message_type === 'group' || data.group_id != null) {
       const groupId = Number(data.group_id);
-      return Number.isFinite(groupId) && groupId > 0 ? this.client.pickGroup(groupId) : null;
+      return Number.isFinite(groupId) && groupId > 0 ? this.pickGroup(groupId) : null;
     }
     const sourceGroupId = Number(data.sender?.group_id);
     if (Number.isFinite(sourceGroupId) && sourceGroupId > 0) {
-      return this.client.pickMember(sourceGroupId, userId);
+      return this.pickMember(sourceGroupId, userId);
     }
-    return this.client.pickFriend(userId);
+    return this.pickFriend(userId);
   }
 
   #logInboundHandlerFailure(event: string, error: unknown): void {
@@ -1072,6 +1117,9 @@ export class IcqqEndpoint extends Endpoint<Client> {
       return;
     }
     await this.admit({
+      event,
+      platformSentAt: typeof normalized.raw.time === 'number' && Number.isFinite(normalized.raw.time)
+        ? normalized.timestampMs : undefined,
       id: normalized.messageId,
       conversation: icqqInboundConversation(String(this.#options.id), {
         channelType: 'channel',
@@ -1103,7 +1151,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   }
 
   async #listPendingRequests(): Promise<readonly EndpointPendingRequest[]> {
-    const messages = await this.client.getSystemMsg();
+    const messages = await this.getSystemMsg();
     const rows: EndpointPendingRequest[] = [];
     for (const raw of messages) {
       const msg = raw as unknown as IcqqSystemMessage & { request_type?: string };
@@ -1131,7 +1179,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
 
   async #pullPendingSystemMessages(signal: AbortSignal): Promise<void> {
     try {
-      const messages = await raceAbort(Promise.resolve(this.client.getSystemMsg()), signal);
+      const messages = await raceAbort(Promise.resolve(this.getSystemMsg()), signal);
       for (const raw of messages) {
         signal.throwIfAborted();
         const msg = raw as unknown as IcqqSystemMessage & { request_type?: string };
@@ -1159,8 +1207,9 @@ export class IcqqEndpoint extends Endpoint<Client> {
     }
   }
 
-  async #approveRequest(id: string, remark?: string): Promise<void> {
-    const messages = await this.client.getSystemMsg();
+  async #approveRequest({ requestId: id, remark, signal }: EndpointApproveRequest): Promise<void> {
+    const operation = createEndpointOperation({ signal });
+    const messages = await operation.run(() => this.getSystemMsg());
     const target = messages.find((m) => {
       const msg = m as unknown as IcqqSystemMessage;
       return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
@@ -1168,15 +1217,17 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (!target?.flag) {
       throw new Error(`icqq 未找到待处理请求: ${id}`);
     }
+    const flag = target.flag;
     if ((target as { request_type?: string }).request_type === 'friend') {
-      await this.client.setFriendAddRequest(target.flag, true, remark);
+      await operation.run(() => this.setFriendAddRequest(flag, true, remark));
     } else {
-      await this.client.setGroupAddRequest(target.flag, true);
+      await operation.run(() => this.setGroupAddRequest(flag, true));
     }
   }
 
-  async #rejectRequest(id: string, reason?: string): Promise<void> {
-    const messages = await this.client.getSystemMsg();
+  async #rejectRequest({ requestId: id, reason, signal }: EndpointRejectRequest): Promise<void> {
+    const operation = createEndpointOperation({ signal });
+    const messages = await operation.run(() => this.getSystemMsg());
     const target = messages.find((m) => {
       const msg = m as unknown as IcqqSystemMessage;
       return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
@@ -1184,10 +1235,11 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (!target?.flag) {
       throw new Error(`icqq 未找到待处理请求: ${id}`);
     }
+    const flag = target.flag;
     if ((target as { request_type?: string }).request_type === 'friend') {
-      await this.client.setFriendAddRequest(target.flag, false);
+      await operation.run(() => this.setFriendAddRequest(flag, false));
     } else {
-      await this.client.setGroupAddRequest(target.flag, false, reason);
+      await operation.run(() => this.setGroupAddRequest(flag, false, reason));
     }
   }
 }