@zhin.js/adapter-icqq 1.1.17 → 1.1.19

package/lib/endpoint.js

@@ -1,7 +1,7 @@
 import { parseGroupMessageId, } from '@icqqjs/icqq';
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { Endpoint, } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, createEndpointOperation, } from 'zhin.js/adapter';
 import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments } from '@zhin.js/core';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
@@ -11,7 +11,7 @@ import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned,
 import { icqqNoticeDedupeKey, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
 import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
-import { formatInboundContent, formatOutboundMessages, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+import { formatInboundContent, formatOutboundMessageParts, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
@@ -33,8 +33,8 @@ const BOUND_EVENTS = [
     'system.login.error',
     'system.login.auth',
 ];
-export class IcqqEndpoint extends Endpoint {
-    client;
+export class IcqqEndpoint extends ManagedIcqqClient {
+    [endpointSpec];
     #logger;
     #options;
     endpointName;
@@ -55,63 +55,79 @@ export class IcqqEndpoint extends Endpoint {
     #inflightInbound = new Set();
     #inboundOwner = new AsyncLocalStorage();
     #contentResolver;
-    content;
-    management = Object.freeze({
-        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) => ({
+    #content;
+    loginControl;
+    #reloginTimer;
+    #reloginAttempts = 0;
+    #reloginInFlight;
+    #offlineNoticeAt = 0;
+    #challengeNoticeAt = 0;
+    #management = Object.freeze({
+        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 = {}) => 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 = {}) => 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 = {}) => {
+            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 }) => Array.from((await createEndpointOperation({ signal }).run(() => this.getGroupMemberList(Number(groupId)))).values()),
+        listRequests: (request = {}) => createEndpointOperation(request).run(() => this.#listPendingRequests()),
+        approveRequest: request => this.#approveRequest(request),
+        rejectRequest: request => this.#rejectRequest(request),
+        kickGroupMember: async ({ groupId, userId, signal }) => {
+            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 }) => {
+            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 }) => {
+            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 }) => {
+            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 }) => {
+            const operation = createEndpointOperation({ signal });
+            if (await operation.run(() => this.sendGroupNotice(Number(groupId), content)) === false) {
                 throw new Error('QQ did not confirm the group notice');
             }
         },
     });
-    control = Object.freeze({
-        recall: async (message) => {
+    #control = Object.freeze({
+        recall: async ({ message, signal }) => {
             if (!message.id || message.id.startsWith('outbound:'))
                 return;
-            if (!await this.client.deleteMsg(message.id))
+            if (!await createEndpointOperation({ signal }).run(() => this.deleteMsg(message.id)))
                 throw new Error('QQ did not confirm message recall');
         },
-        addReaction: async (message, emoji) => {
+        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),
@@ -119,14 +135,18 @@ export class IcqqEndpoint extends Endpoint {
             }
             return emoji;
         },
-        removeReaction: async (message, reactionId) => {
+        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),
@@ -135,14 +155,35 @@ export class IcqqEndpoint extends Endpoint {
         },
     });
     constructor(options) {
-        super();
-        const nativeConfig = resolveNativeClientConfig(options.config);
-        this.client = new ManagedIcqqClient(Number(options.config.id), nativeConfig, (operation, error) => this.#handleBackgroundFailure(operation, error));
-        this.#contentResolver = new IcqqContentResolver(this.client);
-        this.content = this.#contentResolver.port;
+        super(Number(options.config.id), resolveNativeClientConfig(options.config), (operation, error) => this.#handleBackgroundFailure(operation, error));
+        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, value) => !this.#options.signal?.aborted && this.#options.loginAssist.submit(taskId, value, this.#options.endpointIdentity),
+            cancel: (taskId, reason) => !this.#options.signal?.aborted && this.#options.loginAssist.cancel(taskId, reason, this.#options.endpointIdentity),
+        });
     }
     #handleBackgroundFailure(operation, error) {
         if (!this.#started || this.#stopped || this.#retiring)
@@ -154,13 +195,162 @@ export class IcqqEndpoint extends Endpoint {
                     : 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())
+        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() {
+        return this.#startRelogin(true);
+    }
+    #startRelogin(resetAttempts) {
+        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() {
+        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) {
+        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() {
+        if (!this.#reloginTimer)
+            return;
+        clearTimeout(this.#reloginTimer);
+        this.#reloginTimer = undefined;
+    }
+    #pendingLoginTasks() {
+        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, willRetry) {
+        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) {
+        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() {
+        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, task) {
         void Promise.resolve(task).catch((error) => {
@@ -170,18 +360,18 @@ export class IcqqEndpoint extends Endpoint {
             }));
         });
     }
-    get transportState() {
+    get #transportState() {
         if (this.#stopped || this.#retiring)
             return 'stopped';
         if (!this.#started)
             return 'idle';
-        if (this.client.isOnline())
+        if (this.isOnline())
             return 'open';
         if (!this.#everOnline)
             return 'connecting';
         return this.#options.config.autoReconnect ? 'reconnecting' : 'closed';
     }
-    async start(signal) {
+    async #startFramework(signal) {
         if (this.#started)
             return;
         signal.throwIfAborted();
@@ -191,7 +381,7 @@ export class IcqqEndpoint extends Endpoint {
         this.#retirementEpoch += 1;
         this.#retirementArmed = false;
         this.#retiring = false;
-        this.client.off('system.online');
+        this.off('system.online');
         this.#started = true;
         let resolveOnline;
         const onlineReady = new Promise((resolve) => {
@@ -202,15 +392,16 @@ export class IcqqEndpoint extends Endpoint {
         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}`);
+            this.#logger.info(`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;
         }
@@ -220,11 +411,11 @@ export class IcqqEndpoint extends Endpoint {
                 this.#resolveStartOnline = undefined;
         }
     }
-    open() {
+    #openFramework() {
         if (this.#retirementArmed) {
             this.#retirementEpoch += 1;
             this.#retirementArmed = false;
-            this.client.off('system.online');
+            this.off('system.online');
             this.#bindSystemOnlineEvent();
         }
         this.#retiring = false;
@@ -236,14 +427,15 @@ export class IcqqEndpoint extends Endpoint {
             });
         }
     }
-    async close() {
+    async #closeFramework() {
         this.#assertExternalLifecycle('close');
         this.#armRetirementFence();
         await Promise.allSettled([...this.#inflightInbound]);
     }
-    async stop() {
-        this.#stopped = true;
+    async #stopFramework() {
         this.#assertExternalLifecycle('stop');
+        this.#stopped = true;
+        this.#clearReloginTimer();
         this.#armRetirementFence();
         await Promise.allSettled([...this.#inflightInbound]);
         this.#resolveStartOnline?.();
@@ -255,7 +447,7 @@ export class IcqqEndpoint extends Endpoint {
             // 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);
+                this.off(event);
         }
         // `Client.logout()` sends an account-level unregister packet before it
         // closes this transport. During config HMR the replacement endpoint for
@@ -263,7 +455,7 @@ export class IcqqEndpoint extends Endpoint {
         // 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();
@@ -281,38 +473,49 @@ export class IcqqEndpoint extends Endpoint {
         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 }) {
+    async #sendFramework({ conversation, payload, signal }) {
         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();
+        const sendNative = (target, message) => {
+            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;
-            for (const [index, message] of messages.entries()) {
+            const parts = [];
+            for (const [index, { message, sourceIndices }] of messages.entries()) {
                 const preview = formatIcqqSendablePreview(message);
                 let result;
                 try {
-                    result = await this.#sendNative(parsed, message);
+                    result = await operation.run(() => sendNative(parsed, message));
                 }
                 catch (error) {
                     this.#logger.warn(formatCompact({
@@ -324,66 +527,55 @@ export class IcqqEndpoint extends Endpoint {
                     }));
                     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, sentAt) {
-        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(target, message) {
         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}`);
                     }
@@ -395,11 +587,11 @@ export class IcqqEndpoint extends Endpoint {
         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':
@@ -409,13 +601,13 @@ export class IcqqEndpoint extends Endpoint {
         }
         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);
+                return this.sendGuildMsg(target.guildId, target.channelId, message);
         }
     }
     admit(msg) {
@@ -428,7 +620,7 @@ export class IcqqEndpoint extends Endpoint {
         this.#inflightInbound.add(settlement);
         let operation;
         try {
-            operation = this.#inboundOwner.run(owner, run);
+            operation = this.#inboundOwner.run(owner, () => this[endpointSpec].events.run(run));
         }
         catch (error) {
             this.#inflightInbound.delete(settlement);
@@ -477,7 +669,9 @@ export class IcqqEndpoint extends Endpoint {
             + (msg.sender ? ` from ${msg.sender.name ?? msg.sender.id}` : '')
             + (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,
@@ -503,80 +697,81 @@ export class IcqqEndpoint extends Endpoint {
     #bindClientEvents() {
         this.#bindNativeEvents();
         const safe = (label, fn) => {
-            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() {
-        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({
@@ -601,7 +796,7 @@ export class IcqqEndpoint extends Endpoint {
     #bindNativeEvents() {
         this.#disposeNativeEvents?.();
         let matchedName;
-        const registration = this.client.on((eventName) => {
+        const registration = this.on((eventName) => {
             matchedName = typeof eventName === 'string' && !eventName.startsWith('internal.')
                 ? eventName
                 : undefined;
@@ -614,7 +809,7 @@ export class IcqqEndpoint extends Endpoint {
         this.#disposeNativeEvents = () => registration();
     }
     #emitNativeEvent(name, event) {
-        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,
@@ -624,17 +819,22 @@ export class IcqqEndpoint extends Endpoint {
         });
     }
     #handleLoginChallenge(step, event) {
+        if (this.#retiring || this.#stopped || this.#options.signal?.aborted)
+            return;
         const payload = serializeIcqqEvent(event) ?? (event && typeof event === 'object'
             ? event
             : 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,
@@ -653,14 +853,14 @@ export class IcqqEndpoint extends Endpoint {
         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({
@@ -672,7 +872,7 @@ export class IcqqEndpoint extends Endpoint {
         });
     }
     #dispatchIcqqSystemSideEvent(type, payload) {
-        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,
@@ -764,6 +964,8 @@ export class IcqqEndpoint extends Endpoint {
             }));
         }
         await this.#deliverInbound({
+            event,
+            platformSentAt: normalized.timestampMs,
             id: normalized.messageId,
             conversation,
             content: formatInboundContent(normalized.rawMessage),
@@ -794,13 +996,13 @@ export class IcqqEndpoint extends Endpoint {
             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, error) {
         this.#logger.warn(formatCompact({
@@ -834,6 +1036,9 @@ export class IcqqEndpoint extends Endpoint {
             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',
@@ -866,7 +1071,7 @@ export class IcqqEndpoint extends Endpoint {
         this.#dispatchIcqqSideEvent(payload);
     }
     async #listPendingRequests() {
-        const messages = await this.client.getSystemMsg();
+        const messages = await this.getSystemMsg();
         const rows = [];
         for (const raw of messages) {
             const msg = raw;
@@ -894,7 +1099,7 @@ export class IcqqEndpoint extends Endpoint {
     }
     async #pullPendingSystemMessages(signal) {
         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;
@@ -924,8 +1129,9 @@ export class IcqqEndpoint extends Endpoint {
             }));
         }
     }
-    async #approveRequest(id, remark) {
-        const messages = await this.client.getSystemMsg();
+    async #approveRequest({ requestId: id, remark, signal }) {
+        const operation = createEndpointOperation({ signal });
+        const messages = await operation.run(() => this.getSystemMsg());
         const target = messages.find((m) => {
             const msg = m;
             return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
@@ -933,15 +1139,17 @@ export class IcqqEndpoint extends Endpoint {
         if (!target?.flag) {
             throw new Error(`icqq 未找到待处理请求: ${id}`);
         }
+        const flag = target.flag;
         if (target.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, reason) {
-        const messages = await this.client.getSystemMsg();
+    async #rejectRequest({ requestId: id, reason, signal }) {
+        const operation = createEndpointOperation({ signal });
+        const messages = await operation.run(() => this.getSystemMsg());
         const target = messages.find((m) => {
             const msg = m;
             return msg.flag === id || (msg.seq != null && String(msg.seq) === id);
@@ -949,11 +1157,12 @@ export class IcqqEndpoint extends Endpoint {
         if (!target?.flag) {
             throw new Error(`icqq 未找到待处理请求: ${id}`);
         }
+        const flag = target.flag;
         if (target.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));
         }
     }
 }