@agentunion/fastaun 0.5.4 → 0.5.6

package/dist/client.js

@@ -23,7 +23,6 @@ import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, Permiss
 import { EventDispatcher } from './events.js';
 import { LocalTokenStore } from './keystore/local-token-store.js';
 import { AUNLogger } from './logger.js';
-import { normalizeGroupId } from './group-id.js';
 import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
@@ -32,6 +31,7 @@ import { GroupIndexMetaCache } from './group-index.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
 import { MessageDeliveryEngine } from './client/delivery.js';
+import { normalizeGroupMentionMode } from './client/mention-mode.js';
 import { IdentityRuntimeManager } from './client/identity.js';
 import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
@@ -103,7 +103,7 @@ function getV2DeviceId(dev) {
 }
 const DEFAULT_SESSION_OPTIONS = {
     auto_reconnect: true,
-    heartbeat_interval: 30.0,
+    heartbeat_interval: 0.0,
     token_refresh_before: 1800.0,
     retry: {
         initial_delay: 1.0,
@@ -121,20 +121,6 @@ const RECONNECT_MIN_BASE_DELAY_MS = 1_000;
 const RECONNECT_MAX_BASE_DELAY_MS = 64_000;
 const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
 const MAX_NOTIFY_PAYLOAD_SIZE = 64 * 1024;
-// 心跳间隔下/上限（秒）。0 = 关闭心跳；负值视为 0；其余值 clamp 到 [10, 600]。
-// 服务端通过 hello.heartbeat_interval 与 meta.ping pong 中的同名字段下发。
-const HEARTBEAT_MIN_INTERVAL_SECONDS = 10;
-const HEARTBEAT_MAX_INTERVAL_SECONDS = 600;
-function clampHeartbeatInterval(value) {
-    const n = Number(value);
-    if (!Number.isFinite(n) || n <= 0)
-        return 0;
-    if (n < HEARTBEAT_MIN_INTERVAL_SECONDS)
-        return HEARTBEAT_MIN_INTERVAL_SECONDS;
-    if (n > HEARTBEAT_MAX_INTERVAL_SECONDS)
-        return HEARTBEAT_MAX_INTERVAL_SECONDS;
-    return n;
-}
 // P1-23: 非幂等方法使用更长超时（35s），避免 SDK 10s 超时 < gateway 30s 处理时间
 const NON_IDEMPOTENT_TIMEOUT_MS = 35_000;
 const NON_IDEMPOTENT_METHODS = new Set([
@@ -227,7 +213,9 @@ function clampReconnectDelayMs(value, fallback, upper = RECONNECT_MAX_BASE_DELAY
     return Math.min(Math.max(ms, RECONNECT_MIN_BASE_DELAY_MS), upper);
 }
 function reconnectSleepDelayMs(baseDelay, maxBaseDelay) {
-    return baseDelay + Math.random() * maxBaseDelay;
+    // 抖动只随当前退避基数增长，并限制在 maxBaseDelay 内。
+    const jitterLimit = Math.min(Math.max(baseDelay, 0), Math.max(maxBaseDelay - baseDelay, 0));
+    return baseDelay + Math.random() * jitterLimit;
 }
 /** peer 证书缓存 TTL（1 小时） */
 const PEER_CERT_CACHE_TTL = 3600;
@@ -400,7 +388,6 @@ function createAgentMdManagerForRuntime(opts) {
             if (current?.aid === target) {
                 if (!expectedFp || certMatchesFingerprint(current.certPem, expectedFp))
                     return current;
-                throw new StateError(`current AID certificate fingerprint mismatch for ${target}`);
             }
             if (!opts.gateway.get()) {
                 try {
@@ -445,6 +432,7 @@ export class AUNClient {
     _lastErrorCode = null;
     /** Gateway URL */
     _gatewayUrl = null;
+    _gatewayCandidates = [];
     /** 是否正在关闭 */
     _closing = false;
     /** 事件调度器 */
@@ -662,9 +650,28 @@ export class AUNClient {
         // P2P 消息撤回推送：在线 push 与 pull tombstone 去重后再发布给应用层
         this._dispatcher.subscribe('_raw.message.recalled', (data) => this._safeAsync(this._onRawMessageRecalled(data)));
         // V2 P2P 推送通知：收到通知后自动走 message.v2.pull 拉取并解密
-        this._dispatcher.subscribe('_raw.peer.v2.message_received', (data) => this._safeAsync(this._onV2PushNotification(data)));
+        this._dispatcher.subscribe('_raw.peer.v2.message_received', (data) => {
+            const ns = this._aid ? `p2p:${this._aid}` : '';
+            const hasInline = isJsonObject(data)
+                && isJsonObject(data.inline_message);
+            const inlineGeneration = hasInline ? this._delivery.captureInlineAckGeneration() : undefined;
+            this._safeAsync(hasInline
+                ? this._delivery.runPushProcessSerialized(ns, () => this._onV2PushNotification(data, 'v2', inlineGeneration), inlineGeneration)
+                : this._onV2PushNotification(data, 'v2'));
+        });
         // V2 群组消息推送通知：收到通知后自动走 group.v2.pull 拉取并解密
-        this._dispatcher.subscribe('_raw.group.v2.message_created', (data) => this._safeAsync(this._onRawGroupV2MessageCreated(data)));
+        this._dispatcher.subscribe('_raw.group.v2.message_created', (data) => {
+            const groupId = isJsonObject(data)
+                ? String(data.group_id ?? '').trim()
+                : '';
+            const hasInline = isJsonObject(data)
+                && String(data.kind ?? '').trim() !== 'group.online_unread_hint'
+                && isJsonObject(data.inline_message);
+            const inlineGeneration = hasInline ? this._delivery.captureInlineAckGeneration() : undefined;
+            this._safeAsync(hasInline
+                ? this._delivery.runPushProcessSerialized(groupId ? `group:${groupId}` : '', () => this._onRawGroupV2MessageCreated(data, 'v2', inlineGeneration), inlineGeneration)
+                : this._onRawGroupV2MessageCreated(data, 'v2'));
+        });
         // 群组消息推送：自动解密后 re-publish
         this._dispatcher.subscribe('_raw.group.message_created', (data) => this._onRawGroupMessageCreated(data));
         // 群组消息撤回推送：在线 push 通道，与 pull 双 tombstone 兜底互补（SDK 去重只回调一次）
@@ -918,8 +925,8 @@ export class AUNClient {
     getPeer(aid) {
         return this._peerDirectory.getPeer(aid);
     }
-    async lookupPeer(aid) {
-        return this._peerDirectory.lookupPeer(aid);
+    async lookupPeer(aid, certFingerprint) {
+        return this._peerDirectory.lookupPeer(aid, certFingerprint);
     }
     peers() {
         return this._peerDirectory.peers();
@@ -1420,15 +1427,16 @@ export class AUNClient {
         }
         if (targetGroupId) {
             const eventMethod = AUNClient._validateNotifyEventMethod(method);
-            const normalizedGroupId = normalizeGroupId(targetGroupId);
-            if (!normalizedGroupId) {
+            if (!targetGroupId) {
                 throw new ValidationError('group_id is required for group notify');
             }
             const routeParams = {
-                group_aid: normalizedGroupId,
-                group_id: normalizedGroupId,
+                group_id: targetGroupId,
                 deliver: { method: eventMethod, params: payload },
             };
+            const explicitGroupAid = String(options.group_aid ?? options.groupAid ?? '').trim();
+            if (explicitGroupAid)
+                routeParams.group_aid = explicitGroupAid;
             if (ttl !== undefined)
                 routeParams.ttl_ms = ttl;
             await this._transport.notify('notification/group.route', routeParams);
@@ -1454,17 +1462,26 @@ export class AUNClient {
     }
     async _callRawV2Rpc(method, params) {
         const p = { ...(params ?? {}) };
-        const rpcBackground = Boolean(p._rpc_background) || this._backgroundRpcDepth > 0;
+        const forceForeground = Boolean(p._rpc_foreground);
+        const rpcBackground = !forceForeground
+            && (Boolean(p._rpc_background) || this._backgroundRpcDepth > 0);
+        delete p._rpc_foreground;
         delete p._rpc_background;
         delete p._pull_gate_locked;
         delete p._skip_auto_ack;
         delete p.skip_auto_ack;
         delete p._group_cursor_params;
-        if (method.startsWith('group.') && p.group_aid !== undefined && p.group_aid !== null) {
-            p.group_aid = normalizeGroupId(String(p.group_aid)) || String(p.group_aid);
-        }
-        else if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
-            p.group_aid = normalizeGroupId(String(p.group_id)) || String(p.group_id);
+        if (method.startsWith('group.')) {
+            const rawGroupAid = String(p.group_aid ?? p.groupAid ?? '').trim();
+            const rawGroupId = String(p.group_id ?? p.groupId ?? '').trim();
+            if (rawGroupId)
+                p.group_id = rawGroupId;
+            else if (rawGroupAid)
+                p.group_id = rawGroupAid;
+            if (rawGroupAid)
+                p.group_aid = rawGroupAid;
+            delete p.groupAid;
+            delete p.groupId;
         }
         if (method.startsWith('group.') && p.device_id === undefined) {
             p.device_id = this._deviceId;
@@ -1711,8 +1728,11 @@ export class AUNClient {
             this._backgroundRpcDepth = Math.max(0, this._backgroundRpcDepth - 1);
         }
     }
-    async _runPullSerialized(key, operation) {
-        return await this._rpcPipeline.runPullSerialized(key, operation);
+    async _runPullSerialized(key, operation, background = false) {
+        return await this._rpcPipeline.runPullSerialized(key, operation, background);
+    }
+    async _tryRunInlineRealtime(namespace, seq, operation) {
+        return await this._rpcPipeline.tryRunInlineRealtime(namespace, seq, operation);
     }
     async _tryRunBackgroundPull(key, operation, followupOnMessages = false, onBusy) {
         if (key && this._isPullResponseProcessing(key)) {
@@ -1749,16 +1769,6 @@ export class AUNClient {
     async _publishPulledMessage(event, ns, seq, payload) {
         return this._delivery.publishPulledMessage(event, ns, seq, payload);
     }
-    _markPulledSeqDelivered(ns, seq) {
-        // Pull 批次是 after_seq 之后服务端当前可用的结果集，可能跨过永久空洞。
-        // 这里仅在应用层发布返回后推进已交付游标，不能改成 push 的相邻 seq 门控。
-        const seqNum = Number(seq);
-        if (!ns || !Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0)
-            return false;
-        const before = this._seqTracker.getContiguousSeq(ns);
-        this._seqTracker.forceContiguousSeq(ns, seqNum);
-        return this._seqTracker.getContiguousSeq(ns) !== before;
-    }
     _markOrderedSeqDelivered(ns, seq) {
         if (!ns || !Number.isFinite(seq) || !Number.isInteger(seq) || seq <= 0)
             return false;
@@ -1768,21 +1778,21 @@ export class AUNClient {
     }
     _extractGroupIdFromResult(result) {
         const group = isJsonObject(result.group) ? result.group : null;
-        const gid = group ? String(group.group_aid ?? group.group_id ?? '') : '';
+        const gid = group ? String(group.group_id ?? group.groupId ?? group.group_aid ?? group.groupAid ?? '') : '';
         if (gid)
             return gid;
-        const directGid = String(result.group_aid ?? result.group_id ?? '');
+        const directGid = String(result.group_id ?? result.groupId ?? result.group_aid ?? result.groupAid ?? '');
         if (directGid)
             return directGid;
         const member = isJsonObject(result.member) ? result.member : null;
-        return member ? String(member.group_aid ?? member.group_id ?? '') : '';
+        return member ? String(member.group_id ?? member.groupId ?? member.group_aid ?? member.groupAid ?? '') : '';
     }
     async _onRawGroupChanged(data) {
         const tStart = Date.now();
         try {
             if (isJsonObject(data)) {
                 const d = data;
-                const groupId = String(d.group_aid ?? d.group_id ?? '');
+                const groupId = String(d.group_id ?? d.group_aid ?? '');
                 const action = String(d.action ?? '');
                 this._clientLog.debug(`_onRawGroupChanged enter: group_id=${groupId}, action=${action}, event_seq=${String(d.event_seq ?? '')}`);
                 // 验签：有 client_signature 就验，没有默认安全（H20: 严格 boolean）
@@ -2095,6 +2105,7 @@ export class AUNClient {
     _resetSeqTrackingState() {
         this._saveSeqTrackerState();
         this._resetV2IdentityRuntime();
+        this._delivery.resetInlineAckState();
         this._seqTracker = new SeqTracker();
         this._seqTrackerContext = null;
         this._gapFillDone.clear();
@@ -2116,6 +2127,7 @@ export class AUNClient {
         if (nextContext === this._seqTrackerContext)
             return;
         this._saveSeqTrackerState();
+        this._delivery.resetInlineAckState();
         this._seqTracker = new SeqTracker();
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
@@ -2139,6 +2151,9 @@ export class AUNClient {
     _persistSeq(ns, forceSeq) {
         return this._delivery.persistSeq(ns, forceSeq);
     }
+    _commitSeqTrackerState(ns) {
+        return this._delivery.commitSeqTrackerState(ns);
+    }
     _persistRepairedSeq(ns) {
         return this._delivery.persistRepairedSeq(ns);
     }
@@ -2258,8 +2273,20 @@ export class AUNClient {
                     this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
                 }
             }
+            if (!this._transport.isConnected()) {
+                throw new ConnectionError('websocket disconnected during authentication');
+            }
+            this._serverKicked = false;
+            this._lastDisconnectInfo = null;
             this._state = 'ready';
             this._connectedAt = Date.now();
+            if (Array.isArray(params.gateways)) {
+                this._gatewayCandidates = [...new Set(params.gateways
+                        .map((item) => String(item ?? '').trim()).filter(Boolean))];
+            }
+            else if (gatewayUrl) {
+                this._gatewayCandidates = [gatewayUrl];
+            }
             this._clientLog.debug(`auth complete, connection ready: aid=${this._aid ?? ''}, gateway=${gatewayUrl}`);
             await this._dispatcher.publish('state_change', { state: this._publicState(this._state), gateway: gatewayUrl });
             // auth 阶段 aid 可能被 identity 覆盖（上方 this._aid = identity.aid）；
@@ -2434,6 +2461,9 @@ export class AUNClient {
     async _getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint) {
         return await this._v2E2EE.getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint);
     }
+    async _fetchV2SenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint) {
+        return await this._v2E2EE.fetchSenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint);
+    }
     _cacheV2PeerIKFromDevice(dev, fallbackAid = '') {
         const session = this._v2Session;
         if (!session || !isJsonObject(dev))
@@ -2489,11 +2519,11 @@ export class AUNClient {
         return await this._callRawV2Rpc('group.ack_messages', p);
     }
     /** V2 Group ack。 */
-    async _ackGroupV2(groupId, upToSeq) {
-        return await this._v2E2EE.ackGroupV2(groupId, upToSeq);
+    async _ackGroupV2(groupId, upToSeq, groupAid) {
+        return await this._v2E2EE.ackGroupV2(groupId, upToSeq, groupAid);
     }
     /** 解密单条 V2 pull 消息。缺 sender IK 时先入 pending，后台补齐后重试。 */
-    async _decryptV2Message(msg, allowPending = true) {
+    async _decryptV2Message(msg, allowPending = true, emitUndecryptable = true, rotateKeys = true, observeAgentMd = true) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -2509,7 +2539,8 @@ export class AUNClient {
             return null;
         }
         const e2eeMeta = this._v2E2eeMeta(envelope);
-        this._agentMdManager.observeEnvelope(envelope);
+        if (observeAgentMd)
+            this._agentMdManager.observeEnvelope(envelope);
         let spkId = '';
         let recipientKeySource = '';
         if (isJsonObject(envelope.recipient)) {
@@ -2570,16 +2601,20 @@ export class AUNClient {
             };
             this._attachV2EnvelopeMetadata(event, e2eeMeta);
             this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
-            await this._dispatcher.publish(undecryptableEvent, event);
+            if (emitUndecryptable)
+                await this._dispatcher.publish(undecryptableEvent, event);
             return null;
         }
         this._clientLog.debug(`V2 decrypt key lookup ok: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}, ik_len=${ikPriv.byteLength}, spk_len=${spkPriv?.byteLength ?? 0}`);
         const fromAid = String(msg.from_aid ?? '');
         const senderDeviceId = String(aad.from_device ?? '');
         const senderCertFingerprint = String(envelope.sender_cert_fingerprint ?? '').trim().toLowerCase();
-        const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
+        let senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
         if (!senderPubDer) {
             this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
+            senderPubDer = await this._fetchV2SenderIKOnce(fromAid, senderDeviceId, groupIdForKeys, senderCertFingerprint);
+        }
+        if (!senderPubDer) {
             if (allowPending) {
                 this._scheduleV2SenderIKPending({ msg, fromAid, senderDeviceId, groupId: groupIdForKeys });
                 return null;
@@ -2599,7 +2634,8 @@ export class AUNClient {
             };
             this._attachV2EnvelopeMetadata(event, e2eeMeta);
             this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
-            await this._dispatcher.publish(undecryptableEvent, event);
+            if (emitUndecryptable)
+                await this._dispatcher.publish(undecryptableEvent, event);
             return null;
         }
         let plaintext;
@@ -2623,29 +2659,18 @@ export class AUNClient {
             };
             this._attachV2EnvelopeMetadata(event, e2eeMeta);
             this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
-            await this._dispatcher.publish(undecryptableEvent, event);
+            if (emitUndecryptable)
+                await this._dispatcher.publish(undecryptableEvent, event);
             return null;
         }
         if (plaintext === null) {
             this._clientLog.debug(`V2 decrypt returned null plaintext: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}`);
             return null;
         }
-        // 消费触发 SPK 轮换
-        if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
-            this._v2E2EE.scheduleGroupSpkRotation(groupIdForKeys, { reason: 'group_spk_consumed' });
-        }
-        else if (groupIdForKeys && recipientKeySource === 'peer_device_prekey') {
-            this._v2E2EE.scheduleGroupSpkRegistrationAfterPeerFallback(groupIdForKeys);
-        }
-        else if (!groupIdForKeys && session.isLastUploadedSPK(spkId)) {
-            // P2P SPK 消费触发轮换
-            const callFn = async (method, params) => this.call(method, params);
-            session.rotateSPK(callFn).catch(exc => {
-                this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${formatCaughtError(exc)}`);
-            });
-        }
+        if (rotateKeys)
+            this._scheduleV2KeyRotationForMessage(msg, envelope);
         const e2ee = this._v2E2eeMeta(envelope);
-        const result = {
+        let result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             to: this._aid ?? '',
@@ -2663,9 +2688,65 @@ export class AUNClient {
             result.slot_id = msg.slot_id;
         attachGatewayProximity(result, msg);
         this._attachV2EnvelopeMetadata(result, e2ee);
+        if (groupIdForKeys)
+            result = normalizeGroupMentionMode(result, msg, envelope);
         this._logMessageDebug('decrypt-ok', 'v2.decrypt', groupIdForKeys ? 'group.message_created' : 'message.received', result);
         return result;
     }
+    /** inline 在绑定、游标提交和 ACK 都成功后才调用，避免伪造 Head 过早消耗密钥。 */
+    _postInlineV2CommitAndAck(msg) {
+        const envelopeJson = msg.envelope_json;
+        if (typeof envelopeJson !== 'string' || !envelopeJson)
+            return;
+        try {
+            const envelope = JSON.parse(envelopeJson);
+            this._agentMdManager.observeEnvelope(envelope);
+            this._scheduleV2KeyRotationForMessage(msg, envelope);
+        }
+        catch (exc) {
+            this._clientLog.debug(`inline V2 post-ack rotation skipped: invalid envelope: ${formatCaughtError(exc)}`);
+        }
+    }
+    _scheduleV2KeyRotationForMessage(msg, envelope) {
+        const session = this._v2Session;
+        if (!session)
+            return;
+        let spkId = '';
+        let recipientKeySource = '';
+        if (isJsonObject(envelope.recipient)) {
+            const recipient = envelope.recipient;
+            spkId = String(recipient.spk_id ?? '');
+            recipientKeySource = String(recipient.key_source ?? '');
+        }
+        else if (Array.isArray(envelope.recipients)) {
+            spkId = String(msg.spk_id ?? '');
+            for (const row of envelope.recipients) {
+                if (!Array.isArray(row) || row.length < 6
+                    || String(row[0] ?? '') !== this._aid
+                    || (String(row[1] ?? '') !== this._deviceId && String(row[1] ?? '') !== ''))
+                    continue;
+                if (!spkId)
+                    spkId = String(row[5] ?? '');
+                if (row.length > 3)
+                    recipientKeySource = String(row[3] ?? '');
+                break;
+            }
+        }
+        const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
+        const groupIdForKeys = String(aad.group_id ?? msg.group_id ?? '').trim();
+        if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
+            this._v2E2EE.scheduleGroupSpkRotation(groupIdForKeys, { reason: 'group_spk_consumed' });
+        }
+        else if (groupIdForKeys && recipientKeySource === 'peer_device_prekey') {
+            this._v2E2EE.scheduleGroupSpkRegistrationAfterPeerFallback(groupIdForKeys);
+        }
+        else if (!groupIdForKeys && session.isLastUploadedSPK(spkId)) {
+            const callFn = async (method, params) => this.call(method, params);
+            session.rotateSPK(callFn).catch(exc => {
+                this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${formatCaughtError(exc)}`);
+            });
+        }
+    }
     _v2E2eeMeta(envelope) {
         const suite = String(envelope.suite ?? '');
         const meta = {
@@ -2785,8 +2866,8 @@ export class AUNClient {
     async _v2AutoConfirmPendingProposals() {
         return this._groupState.autoConfirmPendingProposals();
     }
-    async _onV2PushNotification(data) {
-        return this._delivery.onV2PushNotification(data);
+    async _onV2PushNotification(data, expectedVersion, inlineGeneration) {
+        return this._delivery.onV2PushNotification(data, expectedVersion, inlineGeneration);
     }
     async _onV2StateProposed(data) {
         return this._groupState.onV2StateProposed(data);
@@ -2797,8 +2878,8 @@ export class AUNClient {
     async _onV2StateConfirmed(data) {
         return this._groupState.onV2StateConfirmed(data);
     }
-    async _onRawGroupV2MessageCreated(data) {
-        return this._delivery.onRawGroupV2MessageCreated(data);
+    async _onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration) {
+        return this._delivery.onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration);
     }
     /** Push 通知带 payload 时的就地解密（复用 _decryptV2Message） */
     async _decryptV2PushMessage(data) {
@@ -2806,20 +2887,35 @@ export class AUNClient {
     }
     /** 按当前 AID 发现 Gateway；用于 authenticate()/connect() 的新入口。 */
     async _resolveGatewayForAid(aid) {
+        const gateways = await this._resolveGatewayCandidatesForAid(aid);
+        return gateways[0];
+    }
+    /** 发现并缓存全部 Gateway 候选，供首连和自动重连故障转移使用。 */
+    async _resolveGatewayCandidatesForAid(aid) {
         const resolvedAid = String(aid ?? this._aid ?? '').trim();
         if (!resolvedAid) {
             throw new StateError('gateway discovery requires a loaded AID');
         }
-        if (this._gatewayUrl)
-            return this._gatewayUrl;
+        if (this._gatewayCandidates.length > 0)
+            return [...this._gatewayCandidates];
+        if (this._gatewayUrl) {
+            this._gatewayCandidates = [this._gatewayUrl];
+            return [...this._gatewayCandidates];
+        }
         try {
             const loadMetadata = this._tokenStore.loadMetadata;
-            const cachedGateway = typeof loadMetadata === 'function'
-                ? String(loadMetadata.call(this._tokenStore, resolvedAid)?.gateway_url ?? '').trim()
-                : '';
+            const metadata = typeof loadMetadata === 'function'
+                ? loadMetadata.call(this._tokenStore, resolvedAid)
+                : null;
+            const cachedList = isJsonObject(metadata) && Array.isArray(metadata.gateway_urls)
+                ? metadata.gateway_urls.map((item) => String(item ?? '').trim()).filter(Boolean)
+                : [];
+            const cachedGateway = cachedList[0]
+                ?? (isJsonObject(metadata) ? String(metadata.gateway_url ?? '').trim() : '');
             if (cachedGateway) {
-                this._gatewayUrl = cachedGateway;
-                return cachedGateway;
+                this._gatewayCandidates = [...new Set([cachedGateway, ...cachedList])];
+                this._gatewayUrl = this._gatewayCandidates[0];
+                return [...this._gatewayCandidates];
             }
         }
         catch {
@@ -2830,22 +2926,38 @@ export class AUNClient {
         const portSuffix = this._configModel.discoveryPort ? `:${this._configModel.discoveryPort}` : '';
         const aidUrl = `https://${resolvedAid}${portSuffix}/.well-known/aun-gateway`;
         const gatewayDomainUrl = `https://gateway.${issuerDomain}${portSuffix}/.well-known/aun-gateway`;
-        const candidates = this._configModel.verifySsl ? [aidUrl, gatewayDomainUrl] : [gatewayDomainUrl, aidUrl];
+        const candidates = [aidUrl, gatewayDomainUrl];
         let lastErr = null;
         for (const url of candidates) {
             try {
-                const gateway = await this._discovery.discover(url);
+                // discoverAll 是生产路径；若调用方注入了旧版/测试 discovery
+                // 替身而只提供 discover，则保留单候选兼容，不影响多候选发现。
+                const discovery = this._discovery;
+                const hasInjectedDiscover = Object.prototype.hasOwnProperty.call(discovery, 'discover')
+                    && typeof discovery.discover === 'function';
+                const discovered = hasInjectedDiscover
+                    ? [await discovery.discover(url)]
+                    : await discovery.discoverAll(url);
+                const gatewayUrls = [...new Set(discovered.map((item) => String(item ?? '').trim()).filter(Boolean))];
+                if (gatewayUrls.length === 0)
+                    throw new ValidationError('gateway discovery returned no candidates');
+                this._gatewayCandidates = gatewayUrls;
+                const gateway = gatewayUrls[0];
                 this._gatewayUrl = gateway;
                 try {
                     const saveMetadata = this._tokenStore.saveMetadata;
                     if (typeof saveMetadata === 'function') {
-                        saveMetadata.call(this._tokenStore, resolvedAid, { gateway_url: gateway, gateway_cached_at: Date.now() });
+                        saveMetadata.call(this._tokenStore, resolvedAid, {
+                            gateway_url: gateway,
+                            gateway_urls: gatewayUrls,
+                            gateway_cached_at: Date.now(),
+                        });
                     }
                 }
                 catch {
                     // 缓存写入失败不影响连接。
                 }
-                return gateway;
+                return [...gatewayUrls];
             }
             catch (err) {
                 lastErr = err;
@@ -2856,6 +2968,9 @@ export class AUNClient {
     }
     /** 从参数中解析 Gateway URL */
     _resolveGateway(params) {
+        const explicitGateway = String(params.gateway ?? '').trim();
+        if (explicitGateway)
+            return explicitGateway;
         const gateways = this._resolveGateways(params);
         return gateways[0];
     }
@@ -2872,7 +2987,9 @@ export class AUNClient {
                 throw new ValidationError('relay topology is not implemented in the TypeScript SDK');
             }
         }
-        const gw = params.gateway ?? params.gateways;
+        const gw = Array.isArray(params.gateways) && params.gateways.length > 0
+            ? params.gateways
+            : params.gateway;
         if (Array.isArray(gw)) {
             const urls = gw.map(g => String(g ?? '')).filter(u => u.length > 0);
             if (urls.length > 0)
@@ -2907,7 +3024,13 @@ export class AUNClient {
         if (!accessToken && opts.requireAccessToken === true) {
             throw new StateError('connect requires non-empty access_token');
         }
-        const gateway = String(request.gateway ?? this._gatewayUrl ?? '');
+        const rawGateways = request.gateways;
+        const normalizedGateways = Array.isArray(rawGateways)
+            ? [...new Set(rawGateways.map((item) => String(item ?? '').trim()).filter(Boolean))]
+            : [];
+        if (normalizedGateways.length > 0)
+            request.gateways = normalizedGateways;
+        const gateway = String(request.gateway ?? normalizedGateways[0] ?? this._gatewayUrl ?? '');
         if (!gateway)
             throw new StateError('connect requires non-empty gateway');
         if (accessToken)
@@ -2969,8 +3092,6 @@ export class AUNClient {
         };
         if ('auto_reconnect' in params)
             options.auto_reconnect = Boolean(params.auto_reconnect);
-        if ('heartbeat_interval' in params)
-            options.heartbeat_interval = Number(params.heartbeat_interval);
         if ('token_refresh_before' in params)
             options.token_refresh_before = Number(params.token_refresh_before);
         if ('retry' in params && isJsonObject(params.retry)) {
@@ -2986,10 +3107,9 @@ export class AUNClient {
     // ── 内部：后台任务 ────────────────────────────────────────
     /** 启动所有后台任务 */
     _startBackgroundTasks() {
-        // 短连接不启动 heartbeat 与 token 刷新（生命周期短，不需要长期会话维护）；
-        // auto_reconnect 仍允许，由 _sessionOptions.auto_reconnect 决定
+        // WebSocket Ping/Pong 由 Gateway 与传输层处理；SDK 不发送 RPC 心跳。
+        // 短连接生命周期短，不需要 token 刷新。
         if (this._sessionOptions.connection_kind !== 'short') {
-            this._startHeartbeatTask();
             this._startTokenRefreshTask();
         }
         this._startV2MaintenanceTasks();
@@ -3011,56 +3131,19 @@ export class AUNClient {
     }
     /** 启动心跳任务 */
     _startHeartbeatTask() {
-        if (this._heartbeatTimer !== null)
-            return;
-        const interval = clampHeartbeatInterval(this._sessionOptions.heartbeat_interval ?? DEFAULT_SESSION_OPTIONS.heartbeat_interval);
-        if (interval <= 0)
-            return;
-        // M25: 把连续失败阈值从 3 次收窄到 2 次。既能容忍一次网络抖动/GC 暂停，
-        // 又把半开连接的检测延迟从 3 个心跳周期降到 2 个。
-        // 真正的 socket 死亡由 ws.on('close') 立即触发 _handleTransportDisconnect，
-        // 不依赖此心跳路径。
-        let consecutiveFailures = 0;
-        const maxFailures = 2;
-        this._heartbeatTimer = setInterval(() => {
-            if (this._closing || this.state !== ConnectionState.READY)
-                return;
-            this._transport.call('meta.ping', {}).then((pong) => {
-                consecutiveFailures = 0;
-                // 服务端可在 pong 中下发新的 heartbeat_interval（秒，0=关闭）
-                if (isJsonObject(pong) && 'heartbeat_interval' in pong) {
-                    this._applyServerHeartbeatInterval(pong.heartbeat_interval, 'pong');
-                }
-            }).catch((exc) => {
-                consecutiveFailures++;
-                this._clientLog.warn(`heartbeat failed (${consecutiveFailures}/${maxFailures}): ${formatCaughtError(exc)}`);
-                this._dispatcher.publish('connection.error', { error: formatCaughtError(exc) }).catch(() => { });
-                if (consecutiveFailures >= maxFailures) {
-                    this._clientLog.warn(`${maxFailures} consecutive heartbeat failures, triggering reconnect`);
-                    this._handleTransportDisconnect(exc instanceof Error ? exc : new Error(String(exc)));
-                }
-            });
-        }, interval * 1000);
-        // 允许 Node.js 进程在只剩定时器时退出
-        if (this._heartbeatTimer && typeof this._heartbeatTimer === 'object' && 'unref' in this._heartbeatTimer) {
-            this._heartbeatTimer.unref();
+        if (this._heartbeatTimer !== null) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
         }
+        this._sessionOptions.heartbeat_interval = 0;
     }
-    /** 服务端通过 hello/pong 下发 heartbeat_interval；clamp 后写入 session_options 并按需重启心跳。 */
-    _applyServerHeartbeatInterval(raw, source) {
-        const newInterval = clampHeartbeatInterval(raw);
-        const oldInterval = clampHeartbeatInterval(this._sessionOptions.heartbeat_interval);
-        if (newInterval === oldInterval)
-            return;
-        this._sessionOptions.heartbeat_interval = newInterval;
-        this._clientLog.debug(`heartbeat_interval updated by ${source}: ${oldInterval} -> ${newInterval}`);
+    /** 忽略旧 Gateway 的 RPC 心跳配置，固定使用 WebSocket Ping/Pong。 */
+    _applyServerHeartbeatInterval(_raw, _source) {
         if (this._heartbeatTimer !== null) {
             clearInterval(this._heartbeatTimer);
             this._heartbeatTimer = null;
         }
-        if (newInterval > 0 && this.state === ConnectionState.READY && !this._closing) {
-            this._startHeartbeatTask();
-        }
+        this._sessionOptions.heartbeat_interval = 0;
     }
     /** 启动 token 刷新任务 */
     _startTokenRefreshTask() {
@@ -3194,7 +3277,7 @@ export class AUNClient {
     }
     // ── 内部：断线重连 ────────────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
-    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015]);
+    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4013, 4014, 4015]);
     /** 处理服务端主动断开通知 event/gateway.disconnect。
      *
      * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。
@@ -3208,7 +3291,11 @@ export class AUNClient {
             ? payload.detail
             : {};
         this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}, detail=${JSON.stringify(detail)}`);
-        this._serverKicked = true;
+        const reasonText = String(reason ?? '').trim().toLowerCase();
+        const retryable = Number(code) === 4012
+            || reasonText.includes('long_connection_already_exists')
+            || reasonText.includes('long connection already exists');
+        this._serverKicked = !retryable;
         // 缓存最近一次 disconnect 信息，让后续 connection.state(connection_failed) 也能带 detail
         this._lastDisconnectInfo = { code, reason, detail };
         // 透传给应用层订阅者
@@ -3230,21 +3317,27 @@ export class AUNClient {
         // 已在重连中则跳过，避免心跳超时和 transport 断线回调重复触发
         if (this._reconnectActive)
             return;
+        // 不等待状态事件或 transport 清理，先隔离已在途的 inline Push 回调。
+        this._delivery.resetInlineAckState();
         // 原子化标志，防止 await 期间并发调用再次进入
         this._reconnectActive = true;
         this._clientLog.warn(`transport disconnected: closeCode=${closeCode ?? 'none'}, error=${error ? formatCaughtError(error) : 'none'}`);
         this._state = 'standby';
         this._stopBackgroundTasks();
-        void this._transport.close().catch((exc) => {
+        try {
+            await this._transport.close();
+        }
+        catch (exc) {
             this._clientLog.debug(`transport cleanup skipped: ${formatCaughtError(exc)}`);
-        });
+        }
         await this._dispatcher.publish('state_change', { state: this._publicState(this._state), error });
         if (!this._sessionOptions.auto_reconnect) {
             this._reconnectActive = false;
             return;
         }
         // 不重连 close code（认证失败/权限错误/被踢等）或服务端通知断开：抑制重连
-        if (this._serverKicked || (closeCode !== undefined && AUNClient._NO_RECONNECT_CODES.has(closeCode))) {
+        const retryableClose = closeCode === 4012;
+        if ((this._serverKicked && !retryableClose) || (closeCode !== undefined && AUNClient._NO_RECONNECT_CODES.has(closeCode))) {
             this._state = 'connection_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
             this._clientLog.warn(`suppressing auto-reconnect: ${reason}`);
@@ -3268,26 +3361,47 @@ export class AUNClient {
         this._reconnectActive = false;
         this._startReconnect(serverInitiated);
     }
-    /** 启动重连循环（默认无限重试 + 指数退避 + 固定上限抖动，仅在不可重试错误、close() 或 max_attempts 耗尽时终止） */
+    /** 启动重连循环（默认无限重试 + 当前基数抖动，仅在不可重试错误、close() 或 max_attempts 耗尽时终止） */
     _startReconnect(serverInitiated = false) {
         if (this._reconnectActive)
             return;
         this._reconnectActive = true;
-        this._reconnectAbort = new AbortController();
+        const reconnectAbort = new AbortController();
+        this._reconnectAbort = reconnectAbort;
         this._clientLog.debug(`reconnect loop started: serverInitiated=${String(serverInitiated)}, aid=${this._aid ?? ''}`);
-        this._reconnectLoop(serverInitiated).catch((exc) => {
+        this._reconnectLoop(serverInitiated, reconnectAbort).catch((exc) => {
             this._clientLog.warn(`reconnect loop error: ${formatCaughtError(exc)}`);
         });
     }
-    /** 重连循环（for 循环 + AbortController，与 JS/Python 对齐） */
-    async _reconnectLoop(serverInitiated) {
+    /** 重连循环入口；无论正常退出还是意外异常，都只清理自己这一代控制器。 */
+    async _reconnectLoop(serverInitiated, reconnectAbort = this._reconnectAbort) {
+        let releasedOwnGeneration = false;
+        try {
+            await this._runReconnectLoop(serverInitiated, reconnectAbort);
+        }
+        finally {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._nextRetryAt = null;
+                this._reconnectActive = false;
+                this._reconnectAbort = null;
+                releasedOwnGeneration = true;
+            }
+        }
+        // 认证成功到重连代际释放之间若再次断线，断线回调会因 _reconnectActive
+        // 被合并；释放后必须复核底层连接，避免留下“状态 ready、实际离线”。
+        if (releasedOwnGeneration && !this._closing && this._state === 'ready' && !this._transport.isConnected()) {
+            await this._handleTransportDisconnect(new ConnectionError('websocket disconnected while reconnect completed'));
+        }
+    }
+    /** 重连循环主体（for 循环 + AbortController，与 JS/Python 对齐） */
+    async _runReconnectLoop(serverInitiated, reconnectAbort) {
         const retry = this._sessionOptions.retry;
         const maxBaseDelay = clampReconnectDelayMs(Number(retry.max_delay ?? 64.0) * 1000, RECONNECT_MAX_BASE_DELAY_MS);
         const maxAttemptsRaw = Number(retry.max_attempts ?? 0);
         const maxAttempts = Number.isFinite(maxAttemptsRaw) && maxAttemptsRaw > 0 ? Math.floor(maxAttemptsRaw) : 0;
         this._retryMaxAttempts = maxAttempts;
         let delay = clampReconnectDelayMs(serverInitiated ? 16_000 : Number(retry.initial_delay ?? 1.0) * 1000, serverInitiated ? 16_000 : RECONNECT_MIN_BASE_DELAY_MS, maxBaseDelay);
-        for (let attempt = 1; !this._reconnectAbort?.signal.aborted; attempt++) {
+        for (let attempt = 1; !reconnectAbort?.signal.aborted; attempt++) {
             if (this._closing)
                 break;
             // max_attempts 检查在循环顶部，覆盖所有路径（含 health-fail）
@@ -3309,22 +3423,25 @@ export class AUNClient {
                 next_retry_at: this._nextRetryAt,
             });
             try {
-                // 固定上限抖动：base=[1s, max_base]，delay=base+rand(0..max_base)。
-                await this._sleep(Math.max(0, this._nextRetryAt - Date.now()));
-                if (this._reconnectAbort?.signal.aborted || this._closing)
+                // 抖动随当前 base 增长且不超过 max_base，避免首次重连被放大到几十秒。
+                await this._sleep(Math.max(0, this._nextRetryAt - Date.now()), reconnectAbort?.signal);
+                if (reconnectAbort?.signal.aborted || this._closing)
                     break;
                 this._state = 'reconnecting';
                 await this._dispatcher.publish('state_change', {
                     state: this._publicState(this._state),
                     attempt,
                 });
-                // 重连前先 GET /health 探测，不健康则跳过本轮
+                // /health 仅作旁路诊断，不能阻止实际 WebSocket 重连。
                 if (this._gatewayUrl) {
-                    const healthy = await this._discovery.checkHealth(this._gatewayUrl, 5_000);
-                    if (!healthy) {
-                        delay = Math.min(delay * 2, maxBaseDelay);
-                        continue;
-                    }
+                    void this._discovery.checkHealth(this._gatewayUrl, 5_000)
+                        .then((healthy) => {
+                        if (!healthy)
+                            this._clientLog.warn(`reconnect health advisory failed: gateway=${this._gatewayUrl}`);
+                    })
+                        .catch((exc) => {
+                        this._clientLog.debug(`reconnect health advisory error: ${formatCaughtError(exc)}`);
+                    });
                 }
                 await this._transport.close();
                 if (this._sessionParams === null) {
@@ -3348,12 +3465,35 @@ export class AUNClient {
                         this._sessionParams.access_token = '';
                     }
                 }
-                await this._connectOnce(this._sessionParams, true);
+                const candidates = this._orderedReconnectGateways(this._sessionParams);
+                let lastGatewayError = null;
+                let connected = false;
+                for (const gateway of candidates) {
+                    const attemptParams = { ...this._sessionParams, gateway };
+                    try {
+                        await this._connectOnce(attemptParams, true);
+                        if (!this._transport.isConnected()) {
+                            throw new ConnectionError('websocket disconnected while reconnecting');
+                        }
+                        this._sessionParams.gateway = gateway;
+                        connected = true;
+                        break;
+                    }
+                    catch (exc) {
+                        lastGatewayError = exc;
+                        await this._transport.close().catch(() => { });
+                        if (candidates.length > 1) {
+                            this._clientLog.warn(`reconnect gateway failed, trying next: gateway=${gateway}, error=${formatCaughtError(exc)}`);
+                        }
+                        if (!AUNClient._shouldRetryReconnect(exc))
+                            throw exc;
+                    }
+                }
+                if (!connected)
+                    throw (lastGatewayError instanceof Error ? lastGatewayError : new ConnectionError('all gateway candidates failed'));
                 // 重连成功，退出循环
                 this._clientLog.debug(`reconnect success: attempt=${attempt}, aid=${this._aid ?? ''}`);
                 this._nextRetryAt = null;
-                this._reconnectActive = false;
-                this._reconnectAbort = null;
                 return;
             }
             catch (exc) {
@@ -3373,17 +3513,39 @@ export class AUNClient {
                 delay = Math.min(delay * 2, maxBaseDelay);
             }
         }
-        this._reconnectActive = false;
-        this._reconnectAbort = null;
+    }
+    /** 每轮重连从当前地址之后开始轮转，避免永远黏在失效的首个 Gateway。 */
+    _orderedReconnectGateways(params) {
+        const raw = Array.isArray(params.gateways) && params.gateways.length > 0
+            ? params.gateways
+            : (this._gatewayCandidates.length > 0 ? this._gatewayCandidates : [params.gateway ?? this._gatewayUrl]);
+        const candidates = [...new Set(raw.map((item) => String(item ?? '').trim()).filter(Boolean))];
+        if (candidates.length <= 1)
+            return candidates;
+        const current = String(this._gatewayUrl ?? params.gateway ?? '').trim();
+        const index = candidates.indexOf(current);
+        const start = index >= 0 ? (index + 1) % candidates.length : 0;
+        return [...candidates.slice(start), ...candidates.slice(0, start)];
     }
     /** 可取消的 sleep，监听 _reconnectAbort.signal，abort 时提前 resolve */
-    _sleep(ms) {
+    _sleep(ms, signal) {
         return new Promise((resolve) => {
-            const timer = setTimeout(resolve, ms);
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', finish);
+                resolve();
+            };
+            const timer = setTimeout(finish, ms);
             this._unrefTimer(timer);
-            const signal = this._reconnectAbort?.signal;
             if (signal) {
-                signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+                if (signal.aborted)
+                    finish();
+                else
+                    signal.addEventListener('abort', finish, { once: true });
             }
         });
     }
@@ -3399,7 +3561,10 @@ export class AUNClient {
     static _shouldRetryReconnect(error) {
         if (error instanceof AuthError) {
             const message = String(error.message ?? '').toLowerCase();
-            if (message.includes('aid_login1_failed') || message.includes('aid_login2_failed')) {
+            if (message.includes('long_connection_already_exists')
+                || message.includes('long connection already exists')
+                || message.includes('aid_login1_failed')
+                || message.includes('aid_login2_failed')) {
                 return true;
             }
             return false;