@zhin.js/adapter-icqq 1.1.17 → 1.1.19

package/src/endpoint.ts

@@ -11,18 +11,33 @@ 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 } from '@zhin.js/core';
-import { EndpointDeliveryError, type MessageRef } from '@zhin.js/im-contract';
+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';
+import type { IcqqLoginControl } from './icqq-login-control.js';
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
 import { IcqqContentResolver } from './content-resolver.js';
 import {
@@ -53,7 +68,7 @@ import {
 } from './outbound-media.js';
 import {
   formatInboundContent,
-  formatOutboundMessages,
+  formatOutboundMessageParts,
   normalizeIcqqImageMedia,
   icqqInboundConversation,
   icqqOutboundTarget,
@@ -68,8 +83,12 @@ 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. */
+  readonly notifier?: AdapterOutageNotifier;
 }
 
 const BOUND_EVENTS = [
@@ -91,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;
@@ -113,69 +132,79 @@ 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;
+  #reloginInFlight?: Promise<void>;
+  #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),
@@ -183,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),
@@ -201,15 +230,36 @@ 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;
+    this.loginControl = Object.freeze({
+      endpointId: this.endpointName,
+      state: () => ({
+        endpointId: this.endpointName,
+        transportState: this.#transportState,
+        online: this.isOnline(),
+        pending: this.#pendingLoginTasks(),
+      }),
+      pending: () => this.#pendingLoginTasks(),
+      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),
+    });
   }
 
   #handleBackgroundFailure(operation: IcqqBackgroundOperation, error: unknown): void {
@@ -221,11 +271,152 @@ 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). */
+  relogin(): Promise<void> {
+    return this.#startRelogin(true);
+  }
+
+  #startRelogin(resetAttempts: boolean): Promise<void> {
+    if (this.#stopped || this.#retiring) {
+      return Promise.reject(new Error('ICQQ endpoint 已停止'));
+    }
+    if (this.#reloginInFlight) return this.#reloginInFlight;
+    if (resetAttempts) this.#reloginAttempts = 0;
+    const task = this.#performRelogin();
+    this.#reloginInFlight = task;
+    void task.catch(() => undefined).finally(() => {
+      if (this.#reloginInFlight === task) this.#reloginInFlight = undefined;
+      if (this.#started && !this.#stopped && !this.#retiring && !this.isOnline()) {
+        this.#scheduleRelogin('relogin_failed');
+      }
+    });
+    return task;
+  }
+
+  async #performRelogin(): Promise<void> {
+    this.#clearReloginTimer();
+    this.cancelReconnect();
+    this.#logger.info(formatCompact({ op: 'icqq_relogin', endpoint: this.endpointName }));
+    try {
+      await this.login(this.#options.config.password);
+    } catch (error) {
+      this.#logger.warn(formatCompact({
+        op: 'icqq_relogin_failed',
+        endpoint: this.endpointName,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      throw error;
+    }
+  }
+
+  #scheduleRelogin(reason: string): void {
+    if (!this.#options.config.autoReconnect || this.#stopped || this.#retiring) return;
+    if (this.#reloginTimer || this.#reloginInFlight) return;
+    if (this.#reloginAttempts >= 8) return;
+    const attempt = this.#reloginAttempts++;
+    const delayMs = Math.min(300_000, 5_000 * (2 ** Math.min(attempt, 5)));
+    this.#logger.info(formatCompact({
+      op: 'icqq_relogin_scheduled',
+      endpoint: this.endpointName,
+      reason,
+      attempt: attempt + 1,
+      delay_ms: delayMs,
+    }));
+    this.#reloginTimer = setTimeout(() => {
+      this.#reloginTimer = undefined;
+      void this.#startRelogin(false).catch(() => {
+        // #performRelogin already scheduled the next attempt.
+      });
+    }, delayMs);
+    this.#reloginTimer.unref?.();
+  }
+
+  #clearReloginTimer(): void {
+    if (!this.#reloginTimer) return;
+    clearTimeout(this.#reloginTimer);
+    this.#reloginTimer = undefined;
+  }
+
+  #pendingLoginTasks(): readonly PendingLoginTask[] {
+    if (this.#options.signal?.aborted) return [];
+    return this.#options.loginAssist.listPending()
+      .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 {
+    const notifier = this.#options.notifier;
+    if (!notifier?.configured) return;
+    const now = Date.now();
+    if (now - this.#offlineNoticeAt < 60_000) return;
+    this.#offlineNoticeAt = now;
+    const recovery = willRetry
+      ? '已开始自动重新登录。'
+      : '请手动重新登录。';
+    const qrCommand = `icqq login qr ${this.endpointName}`;
+    const confirmCommand = `icqq login confirm ${this.endpointName}`;
+    const codeCommand = `icqq login code ${this.endpointName} <内容>`;
+    const text = `[Zhin] ICQQ ${this.endpointName} 掉线（${reason}）。${recovery}\n`
+      + `恢复：在 QQ 回复 \`${qrCommand}\` 获取二维码，扫码后回复 \`${confirmCommand}\`；`
+      + `滑块/短信验证请回复 \`${codeCommand}\`。也可以打开 Console 的 ICQQ 页面完成登录。`;
+    void notifier.send(text).then((sent) => {
+      if (sent) return;
+      this.#logger.warn(formatCompact({
+        op: 'icqq_notify_failed',
+        endpoint: this.endpointName,
+        reason,
+      }));
+    });
+  }
+
+  #notifyChallenge(step: 'qrcode' | 'slider' | 'device' | 'auth'): void {
+    const notifier = this.#options.notifier;
+    if (!notifier?.configured) return;
+    const now = Date.now();
+    if (now - this.#challengeNoticeAt < 30_000) return;
+    this.#challengeNoticeAt = now;
+    const label = step === 'qrcode' ? '二维码验证'
+      : step === 'slider' ? '滑块验证'
+        : step === 'device' ? '设备确认'
+          : '登录确认';
+    const qrCommand = `icqq login qr ${this.endpointName}`;
+    const confirmCommand = `icqq login confirm ${this.endpointName}`;
+    const codeCommand = `icqq login code ${this.endpointName} <内容>`;
+    const text = `[Zhin] ICQQ ${this.endpointName} 需要${label}。\n`
+      + (step === 'qrcode' || step === 'auth'
+        ? `在 QQ 回复 \`${qrCommand}\` 获取二维码，完成后回复 \`${confirmCommand}\`。`
+        : `在 QQ 回复 \`icqq login status ${this.endpointName}\` 查看验证链接，再用 \`${codeCommand}\` 提交验证码；也可以打开 Console 的 ICQQ 页面。`);
+    void notifier.send(text).then((sent) => {
+      if (sent) return;
+      this.#logger.warn(formatCompact({
+        op: 'icqq_notify_failed',
+        endpoint: this.endpointName,
+        reason: `login_${step}`,
+      }));
+    });
+  }
+
+  #notifyRecovered(): void {
+    const notifier = this.#options.notifier;
+    const hadOfflineNotice = this.#offlineNoticeAt > 0;
+    this.#offlineNoticeAt = 0;
+    this.#challengeNoticeAt = 0;
+    if (!notifier?.configured || !hadOfflineNotice) return;
+    void notifier.send(`[Zhin] ICQQ ${this.endpointName} 已重新上线。`).then((sent) => {
+      if (sent) return;
+      this.#logger.warn(formatCompact({ op: 'icqq_notify_failed', endpoint: this.endpointName, reason: 'recovered' }));
+    });
   }
 
   #ignoreReactionAck(action: 'add' | 'remove', task: Promise<unknown> | unknown): void {
@@ -237,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;
@@ -254,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) => {
@@ -265,16 +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) {
-      await this.stop();
+      this.#notifyOffline('start_failed', false);
+      await this.#stopFramework();
       this.#logger.debug(`Failed to connect ICQQ client: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
       throw error;
     } finally {
@@ -283,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;
@@ -300,15 +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> {
-    this.#stopped = true;
+  async #stopFramework(): Promise<void> {
     this.#assertExternalLifecycle('stop');
+    this.#stopped = true;
+    this.#clearReloginTimer();
     this.#armRetirementFence();
     await Promise.allSettled([...this.#inflightInbound]);
     this.#resolveStartOnline?.();
@@ -319,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
@@ -327,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();
@@ -344,36 +537,47 @@ 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<string> {
+  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 = formatOutboundMessages(prepared.content);
+      const messages = formatOutboundMessageParts(prepared.content);
       const parsed = icqqOutboundTarget(conversation);
-      let messageId: string | undefined;
-      for (const [index, message] of messages.entries()) {
+      const parts: EndpointSendPart[] = [];
+      for (const [index, { message, sourceIndices }] of messages.entries()) {
         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',
@@ -383,48 +587,32 @@ export class IcqqEndpoint extends Endpoint<Client> {
             preview: truncatePreview(preview, 120),
           }));
           if (index === 0) throw error;
-          // Earlier parts are already delivered: a retry would duplicate them.
-          throw new EndpointDeliveryError('partial_delivery', `ICQQ delivered ${index} of ${messages.length} message parts`, 'unknown', { cause: error });
+          // Earlier sends completed; retrying can duplicate accepted messages, even without ids.
+          throw new EndpointDeliveryError('partial_delivery', `ICQQ completed ${index} of ${messages.length} message sends`, 'unknown', { cause: error, parts });
         }
         const rawId = result?.message_id;
         const id = (typeof rawId === 'string' || (typeof rawId === 'number' && Number.isFinite(rawId))) && String(rawId).trim() !== ''
           ? String(rawId) : undefined;
-        messageId ??= id;
+        parts.push({ ...(id ? { messageId: id } : {}), ...(sourceIndices ? { sourceIndices } : {}) });
         this.#logger.info(
           `send ${conversation.kind}:${conversation.id} | id: ${id ?? '-'} | ${truncatePreview(preview, 80)}`,
         );
       }
-      // Native share / file APIs return no id; the reply is confirmed by any part that has one.
-      if (!messageId) {
-        throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown');
+      // A resolved share/file call has no message identity; retain that unknown slot in the batch.
+      if (!parts.some(part => part.messageId)) {
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown', { parts });
       }
-      return messageId;
+      return { parts };
     } finally {
-      prepared.dispose();
-    }
-  }
-
-  /**
-   * ICQQ's share API returns no message id; a resolved call only means the server accepted it.
-   * The card is the bot's own newest card message in the conversation history, so read the id
-   * from there (once more after a short wait, history can lag). Undefined keeps the delivery
-   * unconfirmed rather than inventing an id.
-   */
-  async #findOwnCard(
-    history: () => Promise<readonly { message_id?: unknown; time?: number; message?: readonly { type?: string }[]; sender?: { user_id?: number }; user_id?: number }[]>,
-    sentAt: number,
-  ): Promise<string | undefined> {
-    const self = Number(this.client.uin);
-    for (const wait of [0, 500]) {
-      if (wait) await new Promise(resolve => setTimeout(resolve, wait));
-      // A missing or throwing history API must not turn an accepted share into a send failure.
-      const messages = await Promise.resolve().then(history).catch(() => []);
-      const card = [...messages].reverse().find(item => Number(item.sender?.user_id ?? item.user_id) === self
-        && (item.time ?? 0) >= sentAt - 2
-        && (item.message ?? []).some(element => element.type === 'json' || element.type === 'xml' || element.type === 'share'));
-      if (card && card.message_id != null && String(card.message_id).trim()) return String(card.message_id);
+      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();
     }
-    return undefined;
   }
 
   async #sendNative(
@@ -434,22 +622,20 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (isIcqqShareElement(message)) {
       switch (target.kind) {
         case 'private': {
-          const sentAt = Math.floor(Date.now() / 1000);
-          const friend = this.client.pickFriend(target.userId);
+          const friend = this.pickFriend(target.userId);
           await friend.share(message);
-          return { message_id: await this.#findOwnCard(() => friend.getChatHistory(), sentAt) };
+          return {};
         }
         case 'group': {
-          const sentAt = Math.floor(Date.now() / 1000);
-          const group = this.client.pickGroup(target.groupId);
+          const group = this.pickGroup(target.groupId);
           await group.share(message);
-          return { message_id: await this.#findOwnCard(() => group.getChatHistory(), sentAt) };
+          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}`);
           }
@@ -461,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':
@@ -475,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 };
     }
   }
 
@@ -496,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();
@@ -550,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,
@@ -577,79 +765,81 @@ 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();
+      this.#reloginAttempts = 0;
+      this.#notifyRecovered();
       try {
         this.#resolveStartOnline?.();
         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',
@@ -673,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
@@ -689,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,
@@ -703,17 +893,21 @@ 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);
     this.#logSystemEvent(`login.${step}`, event);
+    this.#clearReloginTimer();
+    this.#notifyChallenge(step);
     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,
@@ -734,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({
@@ -754,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,
@@ -847,6 +1041,8 @@ export class IcqqEndpoint extends Endpoint<Client> {
       }));
     }
     await this.#deliverInbound({
+      event,
+      platformSentAt: normalized.timestampMs,
       id: normalized.messageId,
       conversation,
       content: formatInboundContent(normalized.rawMessage),
@@ -878,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 {
@@ -921,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',
@@ -952,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 };
@@ -980,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 };
@@ -1008,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);
@@ -1017,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);
@@ -1033,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));
     }
   }
 }