@agentunion/fastaun 0.2.18 → 0.2.20

package/dist/client.js

@@ -11,6 +11,7 @@
  * - 群组 E2EE 全自动编排（建群/加人/踢人/退出）
  */
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as https from 'node:https';
 import { join } from 'node:path';
@@ -81,7 +82,7 @@ const DEFAULT_SESSION_OPTIONS = {
     },
     timeouts: {
         connect: 5.0,
-        call: 10.0,
+        call: 35.0,
         http: 30.0,
     },
 };
@@ -93,6 +94,20 @@ const GROUP_ROTATION_RETRY_MAX_DELAY_MS = 300_000;
 const PENDING_DECRYPT_LIMIT = 100;
 const PUSHED_SEQS_LIMIT = 50_000;
 const PENDING_ORDERED_LIMIT = 50_000;
+// 心跳间隔下/上限（秒）。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([
@@ -337,6 +352,7 @@ export class AUNClient {
     /** 当前实例上下文 */
     _deviceId;
     _slotId;
+    _connectedAt = 0;
     _connectDeliveryMode;
     _defaultConnectDeliveryMode;
     /** peer 证书缓存 */
@@ -344,13 +360,20 @@ export class AUNClient {
     _peerPrekeysCache = new Map();
     _prekeyReplenishInflight = new Set();
     _prekeyReplenished = new Set();
+    // 当前活跃 prekey：只有这个 prekey 被消费时才触发 replenish 上传
+    _activePrekeyId = '';
+    // 本地 agent.md 文件路径与对应 etag（quoted sha256 hex，与服务端 _agent_md_etag 一致）。
+    // 由 setLocalAgentMdPath() 设置；用于跟服务端 RPC 注入的 _meta.agent_md_etag 比对，
+    // 触发"本地未发布到服务端"或"服务端版本更新"的 UI 提示。
+    _localAgentMdPath = '';
+    _localAgentMdEtag = '';
+    // gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。
+    _remoteAgentMdEtag = '';
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
     /** 惰性群同步：已同步过的 group_id 集合 */
     _groupSynced = new Set();
-    /** 惰性 P2P 同步：是否已同步过 */
-    _p2pSynced = false;
     /** 补洞去重：已完成/进行中的 key -> 开始时间戳，防止重复 pull 同一区间 */
     _gapFillDone = new Map();
     /** 已发布到应用层的 seq 集合（按命名空间），补洞路径 publish 前检查以避免重复分发 */
@@ -375,6 +398,8 @@ export class AUNClient {
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
+    /** 缓存最近一次 gateway.disconnect 信息（含服务端附带的 detail），用于后续 connection.state 透传 */
+    _lastDisconnectInfo = null;
     _logger;
     _clientLog;
     constructor(config, debug = false) {
@@ -428,6 +453,7 @@ export class AUNClient {
             verifySsl: this._configModel.verifySsl,
             logger: this._logger.for('aun_core.transport'),
         });
+        this._transport.setMetaObserver((meta) => this._observeRpcMeta(meta));
         this._e2ee = new E2EEManager({
             identityFn: () => this._identity ?? {},
             deviceIdFn: () => this._deviceId,
@@ -465,6 +491,65 @@ export class AUNClient {
     get aid() {
         return this._aid;
     }
+    /**
+     * 记录本地 agent.md 文件路径并一次性计算 etag（quoted sha256，与服务端一致）。
+     *
+     * - path 为空字符串：清除本地 path 与 etag。
+     * - 文件不存在 / 读取失败：清除 etag 并返回空串，不抛异常（应用可读 getLocalAgentMdEtag()
+     *   为空判断）。
+     * - 浏览器环境无文件系统：直接返回空串，记录 warn 日志。
+     * - 文件变更后需要重新调用 setLocalAgentMdPath() 触发重算（按设计：设置时一次性计算）。
+     *
+     * 返回当前 etag（quoted hex 或空串）。
+     */
+    setLocalAgentMdPath(path) {
+        const rawPath = String(path ?? '').trim();
+        if (!rawPath) {
+            this._localAgentMdPath = '';
+            this._localAgentMdEtag = '';
+            return '';
+        }
+        // 浏览器环境没有 fs，直接退回空串。Node 环境才尝试读文件。
+        const isNode = typeof process !== 'undefined' && !!process.versions?.node;
+        if (!isNode) {
+            this._clientLog.warn(`setLocalAgentMdPath skipped: not running in Node.js (path=${rawPath})`);
+            this._localAgentMdPath = rawPath;
+            this._localAgentMdEtag = '';
+            return '';
+        }
+        this._localAgentMdPath = rawPath;
+        try {
+            const data = fs.readFileSync(rawPath);
+            const digest = crypto.createHash('sha256').update(data).digest('hex');
+            this._localAgentMdEtag = `"${digest}"`;
+        }
+        catch (err) {
+            this._clientLog.warn(`setLocalAgentMdPath 读取失败 path=${rawPath} err=${err instanceof Error ? err.message : String(err)}`);
+            this._localAgentMdEtag = '';
+        }
+        return this._localAgentMdEtag;
+    }
+    /** 返回 setLocalAgentMdPath 计算的 etag；未设置或读取失败时返回空串。 */
+    getLocalAgentMdEtag() {
+        return this._localAgentMdEtag;
+    }
+    /**
+     * 返回 gateway 在最近一次 RPC envelope._meta 注入的服务端 agent.md etag。
+     *
+     * 未收到过则为空串；不阻塞调用，纯内存读。
+     */
+    getRemoteAgentMdEtag() {
+        return this._remoteAgentMdEtag;
+    }
+    /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
+    _observeRpcMeta(meta) {
+        if (!meta || typeof meta !== 'object')
+            return;
+        const etag = String(meta.agent_md_etag ?? '').trim();
+        if (etag) {
+            this._remoteAgentMdEtag = etag;
+        }
+    }
     /** 连接状态 */
     get state() {
         return this._state;
@@ -515,7 +600,7 @@ export class AUNClient {
         this._sessionParams = normalized;
         this._sessionOptions = this._buildSessionOptions(normalized);
         const callTimeoutSec = this._sessionOptions.timeouts.call;
-        this._transport.setTimeout(callTimeoutSec != null ? callTimeoutSec * 1000 : 10_000);
+        this._transport.setTimeout(callTimeoutSec != null ? callTimeoutSec * 1000 : 35_000);
         this._closing = false;
         this._clientLog.debug(`connect enter: gateway=${String(normalized.gateway ?? '')}, device_id=${this._deviceId}`);
         try {
@@ -662,6 +747,7 @@ export class AUNClient {
                     return await this._sendEncrypted(p);
                 }
                 // encrypt=false：明文走通用 RPC 路径；protected_headers/headers 是信封元数据，加密与否都保留
+                this._maybeAppendEchoTraceSend(p);
             }
             // 自动加密：group.send 默认加密（encrypt 默认 True）
             if (method === 'group.send') {
@@ -670,6 +756,7 @@ export class AUNClient {
                 if (encrypt) {
                     return await this._sendGroupEncrypted(p);
                 }
+                this._maybeAppendEchoTraceSend(p);
             }
             if (method === 'group.thought.put') {
                 const encrypt = p.encrypt ?? true;
@@ -744,12 +831,29 @@ export class AUNClient {
                 const gid = (p.group_id ?? '');
                 if (gid) {
                     const ns = `group:${gid}`;
-                    if (rawMessages.length > 0) {
-                        this._seqTracker.onPullResult(ns, rawMessages);
+                    // 区分解密成功 / 失败：失败的 payload 仍是 e2ee.group_encrypted。
+                    const decryptedOnly = [];
+                    let failedCount = 0;
+                    const decryptedMessages = Array.isArray(r.messages) ? r.messages : [];
+                    for (const m of decryptedMessages) {
+                        if (!isJsonObject(m))
+                            continue;
+                        const payload = isJsonObject(m.payload) ? m.payload : {};
+                        const ptype = payload.type;
+                        if (ptype === 'e2ee.group_encrypted') {
+                            failedCount++;
+                            this._enqueuePendingDecrypt(gid, m);
+                        }
+                        else {
+                            decryptedOnly.push(m);
+                        }
+                    }
+                    if (decryptedOnly.length > 0) {
+                        // 仅用解密成功的消息推进 contig；失败的等 retry 解密成功才推进。
+                        this._seqTracker.onPullResult(ns, decryptedOnly);
                     }
                     // ⚠️ 逻辑边界 L4：group retention floor 通道 = cursor.current_seq
                     // 群路径目前无独立 earliest_available_seq 字段；若未来引入 group retention，需新增字段并同步更新此处。
-                    // 与 S2 [1,seq-1] 历史 gap 配合使用，force_contiguous_seq 是跳过空洞的唯一手段。
                     const cursor = isJsonObject(r.cursor) ? r.cursor : null;
                     if (cursor) {
                         const serverAck = Number(cursor.current_seq ?? 0);
@@ -762,9 +866,9 @@ export class AUNClient {
                         }
                     }
                     this._saveSeqTrackerState();
-                    // auto-ack contiguous_seq
+                    // auto-ack：仅当没有解密失败时才 ack。失败时让服务端 cursor 留在原位等 retry。
                     const contig = this._seqTracker.getContiguousSeq(ns);
-                    const shouldAck = rawMessages.length > 0 || (cursor !== null && Number(cursor.current_seq ?? 0) > 0);
+                    const shouldAck = failedCount === 0 && (decryptedOnly.length > 0 || (cursor !== null && Number(cursor.current_seq ?? 0) > 0));
                     if (contig > 0 && shouldAck) {
                         this._transport.call('group.ack_messages', {
                             group_id: gid,
@@ -773,6 +877,10 @@ export class AUNClient {
                             slot_id: this._slotId,
                         }).catch((e) => { this._clientLog.debug(`group.pull auto-ack failed: group=${gid} ${formatCaughtError(e)}`); });
                     }
+                    // 有解密失败时调度 recovery 兜底定时
+                    if (failedCount > 0) {
+                        this._scheduleRecoveryTimeout(gid);
+                    }
                 }
             }
             if (method === 'group.thought.get' && isJsonObject(result)) {
@@ -913,10 +1021,8 @@ export class AUNClient {
         const persistRequired = Boolean(params.persist_required || params.durable);
         const protectedHeaders = this._protectedHeadersFromParams(params);
         this._clientLog.debug(`_sendEncrypted enter: to=${toAid}, message_id=${messageId}`);
-        // 惰性同步：首次发送 P2P 消息时先 pull 一次
-        if (!this._p2pSynced) {
-            await this._lazySyncP2p();
-        }
+        // 惰性 P2P 同步由 connect/reconnect 完成后的 _fillP2pGap 异步触发，
+        // 不再在 send 路径上 await（与 C++ FillP2PGap 行为对齐，避免阻塞用户发送）。
         // 内部发送逻辑，refreshPeerMaterial=true 时强制清缓存重新拉取对端材料
         const sendAttempt = async (refreshPeerMaterial = false) => {
             const recipientPrekeys = refreshPeerMaterial
@@ -929,24 +1035,13 @@ export class AUNClient {
                 timestamp,
                 protectedHeaders,
             });
-            // 多设备过滤：只保留有有效 device_id 的可路由 prekey，
-            // 占位符 PREKEY_FALLBACK_DEVICE_ID 表示服务端未分配真实设备 ID，不可用于多设备路由
+            // 统一 multi-device 路径：必须有 routable prekey
             const routablePrekeys = recipientPrekeys.filter(pk => {
                 const did = String(pk.device_id ?? '').trim();
                 return did && did !== PREKEY_FALLBACK_DEVICE_ID;
             });
-            const canUseMultiDevice = routablePrekeys.length > 0
-                && (routablePrekeys.length > 1 || selfSyncCopies.length > 0);
-            if (!canUseMultiDevice) {
-                return await this._sendEncryptedSingle({
-                    toAid,
-                    payload,
-                    messageId,
-                    timestamp,
-                    prekey: routablePrekeys[0] ?? recipientPrekeys[0],
-                    persistRequired,
-                    protectedHeaders,
-                });
+            if (routablePrekeys.length === 0) {
+                throw new Error(`no registered device prekeys for ${toAid}, cannot send encrypted message`);
             }
             const recipientCopies = await this._buildRecipientDeviceCopies({
                 toAid,
@@ -998,39 +1093,6 @@ export class AUNClient {
             throw exc;
         }
     }
-    async _sendEncryptedSingle(opts) {
-        this._clientLog.debug(`_sendEncryptedSingle enter: to=${opts.toAid}, message_id=${opts.messageId}, has_prekey=${!!opts.prekey}, persist_required=${!!opts.persistRequired}`);
-        let prekey = opts.prekey ?? null;
-        if (!prekey) {
-            this._clientLog.debug(`_sendEncryptedSingle fetching peer prekey: to=${opts.toAid}`);
-            prekey = await this._fetchPeerPrekey(opts.toAid);
-        }
-        const peerCertFingerprint = typeof prekey?.cert_fingerprint === 'string' ? prekey.cert_fingerprint : undefined;
-        const peerCertPem = await this._fetchPeerCert(opts.toAid, peerCertFingerprint);
-        const [envelope, encryptResult] = this._encryptCopyPayload({
-            logicalToAid: opts.toAid,
-            payload: opts.payload,
-            peerCertPem,
-            prekey,
-            messageId: opts.messageId,
-            timestamp: opts.timestamp,
-            protectedHeaders: opts.protectedHeaders,
-        });
-        this._ensureEncryptResult(opts.toAid, encryptResult);
-        this._clientLog.debug(`_sendEncryptedSingle envelope built: to=${opts.toAid}, message_id=${opts.messageId}, scheme=${String(envelope?.scheme ?? '')}`);
-        const sendParams = {
-            to: opts.toAid,
-            payload: envelope,
-            type: 'e2ee.encrypted',
-            encrypted: true,
-            message_id: opts.messageId,
-            timestamp: opts.timestamp,
-        };
-        if (opts.persistRequired) {
-            sendParams.persist_required = true;
-        }
-        return await this._transport.call('message.send', sendParams);
-    }
     async _buildRecipientDeviceCopies(opts) {
         this._clientLog.debug(`_buildRecipientDeviceCopies enter: to=${opts.toAid}, message_id=${opts.messageId}, prekey_count=${opts.prekeys.length}`);
         const recipientCopies = [];
@@ -1322,33 +1384,6 @@ export class AUNClient {
             this._clientLog.warn(`lazy sync group ${groupId} failed: ${formatCaughtError(exc)}`);
         }
     }
-    /** 惰性同步：首次激活 P2P 通道时 pull 最近消息，建立 seq 基线 */
-    async _lazySyncP2p() {
-        this._p2pSynced = true;
-        if (!this._aid)
-            return;
-        try {
-            const ns = `p2p:${this._aid}`;
-            const afterSeq = this._seqTracker.getContiguousSeq(ns);
-            const result = await this._transport.call('message.pull', {
-                after_seq: afterSeq,
-                limit: 200,
-            });
-            const messages = Array.isArray(result?.messages) ? result.messages : [];
-            for (const msg of messages) {
-                const seq = msg?.seq;
-                if (seq != null)
-                    this._seqTracker.onMessageSeq(ns, Number(seq));
-            }
-            if (messages.length > 0) {
-                this._saveSeqTrackerState();
-                this._clientLog.info(`lazy sync P2P: pull ${messages.length} messages, after_seq=${afterSeq}`);
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`lazy sync P2P failed: ${formatCaughtError(exc)}`);
-        }
-    }
     _isGroupEpochTooOldError(exc) {
         const text = String(exc).toLowerCase();
         return text.includes('e2ee epoch too old') || text.includes('epoch below sender membership floor');
@@ -1726,12 +1761,27 @@ export class AUNClient {
         }
         // 拦截 P2P 传输的群组密钥分发/请求/响应消息
         if (await this._tryHandleGroupKeyMessage(msg)) {
+            // group_key 控制消息也要推进 seq tracker + auto-ack，
+            // 否则 fillP2pGap 会因为 contig 卡在此 seq 之前而重复拉取同样的历史消息。
+            const seq = msg.seq;
+            if (seq !== undefined && seq !== null && this._aid) {
+                const ns = `p2p:${this._aid}`;
+                this._seqTracker.onMessageSeq(ns, seq);
+                this._saveSeqTrackerState();
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig > 0) {
+                    this._transport.call('message.ack', {
+                        seq: contig,
+                        device_id: this._deviceId,
+                        slot_id: this._slotId,
+                    }).catch(() => { });
+                }
+            }
             return;
         }
         // P2P 空洞检测
         const seq = msg.seq;
         if (seq !== undefined && seq !== null && this._aid) {
-            this._p2pSynced = true; // 收到推送即视为已激活
             const ns = `p2p:${this._aid}`;
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
@@ -1812,8 +1862,12 @@ export class AUNClient {
         }
         const decrypted = await this._decryptGroupMessage(msg);
         this._clientLog.debug(`group message decrypt done: group=${groupId}, from=${String(msg.from ?? '')}, seq=${String(seq ?? '')}, e2ee=${String(!!decrypted.e2ee)}`);
-        // 只有带 payload 的真实消息，在同步解密/恢复尝试结束后才推进游标。
-        if (groupId && seq !== undefined && seq !== null) {
+        // 解密失败时**不推进 seq tracker / 不 auto-ack**：让服务端 cursor 留在原位，
+        // 等密钥恢复后 retry 解密成功才推进 + ack；recovery 真的失败时由
+        // _retryPendingDecryptMsgs(forceAdvanceOnFail=true) 兜底强制推进。
+        const payloadForCheck = isJsonObject(msg.payload) ? msg.payload : null;
+        const isDecryptFail = payloadForCheck?.type === 'e2ee.group_encrypted' && !decrypted.e2ee;
+        if (!isDecryptFail && groupId && seq !== undefined && seq !== null) {
             const ns = `group:${groupId}`;
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
@@ -1832,10 +1886,12 @@ export class AUNClient {
             this._saveSeqTrackerState();
         }
         // R3: 解密失败 → 不 publish 密文给应用层，入 pending 队列 + 发 undecryptable 事件
-        const payloadForCheck = isJsonObject(msg.payload) ? msg.payload : null;
-        if (payloadForCheck?.type === 'e2ee.group_encrypted' && !decrypted.e2ee) {
-            if (groupId)
+        if (isDecryptFail) {
+            if (groupId) {
                 this._enqueuePendingDecrypt(groupId, msg);
+                // 触发 recovery 兜底定时（30s 后如果仍未解开，强制推进）
+                this._scheduleRecoveryTimeout(groupId);
+            }
             await this._publishAppEvent('group.message_undecryptable', {
                 message_id: msg.message_id,
                 group_id: groupId,
@@ -2059,8 +2115,64 @@ export class AUNClient {
         return this._attachCurrentInstanceContext(payload);
     }
     async _publishAppEvent(event, payload) {
+        if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
+            this._maybeAppendEchoTraceReceive(payload);
+        }
+        // 注入本地/远端 agent.md etag，让应用层判断版本一致性；失败不影响业务。
+        if (isJsonObject(payload)) {
+            try {
+                const localEtag = this._localAgentMdEtag || '';
+                const remoteEtag = this._remoteAgentMdEtag || '';
+                if (localEtag || remoteEtag) {
+                    const obj = payload;
+                    if (!('_agent_md' in obj)) {
+                        obj._agent_md = {
+                            local_etag: localEtag,
+                            remote_etag: remoteEtag,
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                this._clientLog.debug(`agent_md etag inject skipped: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         await this._dispatcher.publish(event, this._normalizePublishedMessagePayload(event, payload));
     }
+    _echoTimestamp() {
+        const now = new Date();
+        const hh = String(now.getHours()).padStart(2, '0');
+        const mm = String(now.getMinutes()).padStart(2, '0');
+        const ss = String(now.getSeconds()).padStart(2, '0');
+        const ms = String(now.getMilliseconds()).padStart(3, '0');
+        return `${hh}:${mm}:${ss}.${ms}`;
+    }
+    _isEchoPayload(payload) {
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            return false;
+        const text = payload.text;
+        if (typeof text !== 'string' || text.length > 4096)
+            return false;
+        return text.split('\n', 1)[0].toLowerCase().includes('echo');
+    }
+    _maybeAppendEchoTraceSend(params) {
+        const payload = params.payload;
+        if (!this._isEchoPayload(payload))
+            return;
+        const uptime = this._connectedAt ? Math.floor((Date.now() - this._connectedAt) / 1000) : 0;
+        const trace = `${this._echoTimestamp()} [AUN-SDK.send] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
+        params.payload = { ...payload, text: payload.text + '\n' + trace };
+    }
+    _maybeAppendEchoTraceReceive(msg) {
+        if (msg.encrypted)
+            return;
+        const payload = msg.payload;
+        if (!this._isEchoPayload(payload))
+            return;
+        const uptime = this._connectedAt ? Math.floor((Date.now() - this._connectedAt) / 1000) : 0;
+        const trace = `${this._echoTimestamp()} [AUN-SDK.receive] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
+        msg.payload = { ...payload, text: payload.text + '\n' + trace };
+    }
     _messageTargetsCurrentInstance(message) {
         if (!isJsonObject(message))
             return true;
@@ -2787,11 +2899,31 @@ export class AUNClient {
         }
         let result;
         if (actualPayload.type === 'e2ee.group_key_distribution') {
+            // 快速跳过已过期的历史 epoch 分发：本地已有更高 epoch 时不发任何 RPC，
+            // 避免 fillP2pGap 拉到大量历史群密钥消息时触发 epoch 编排风暴。
+            const distGroupId = String(actualPayload.group_id ?? '');
+            const distEpoch = Number(actualPayload.epoch ?? 0);
+            if (distGroupId && distEpoch > 0) {
+                const localEpoch = this._groupE2ee.currentEpoch(distGroupId) ?? 0;
+                if (localEpoch >= distEpoch) {
+                    this._clientLog.debug(`skip stale group_key_distribution: group=${distGroupId} msg_epoch=${distEpoch} local_epoch=${localEpoch}`);
+                    return true;
+                }
+            }
             if (!await this._verifyActiveGroupRotationDistribution(actualPayload)) {
                 return true;
             }
         }
         else if (actualPayload.type === 'e2ee.group_key_response') {
+            const respGroupId = String(actualPayload.group_id ?? '');
+            const respEpoch = Number(actualPayload.epoch ?? 0);
+            if (respGroupId && respEpoch > 0) {
+                const localEpoch = this._groupE2ee.currentEpoch(respGroupId) ?? 0;
+                if (localEpoch >= respEpoch) {
+                    this._clientLog.debug(`skip stale group_key_response: group=${respGroupId} msg_epoch=${respEpoch} local_epoch=${localEpoch}`);
+                    return true;
+                }
+            }
             if (!await this._verifyGroupKeyResponseEpoch(actualPayload)) {
                 return true;
             }
@@ -3057,6 +3189,8 @@ export class AUNClient {
     async _uploadPrekey() {
         const prekeyMaterial = this._e2ee.generatePrekey();
         const result = await this._transport.call('message.e2ee.put_prekey', prekeyMaterial);
+        // 上传成功后记录为活跃 prekey
+        this._activePrekeyId = String(prekeyMaterial.prekey_id ?? '');
         return isJsonObject(result) ? { ...result } : { ok: true };
     }
     /**
@@ -3223,23 +3357,47 @@ export class AUNClient {
         queue.push(msg);
         this._pendingDecryptMsgs.set(ns, queue.slice(-PENDING_DECRYPT_LIMIT));
     }
-    async _retryPendingDecryptMsgs(groupId) {
+    async _retryPendingDecryptMsgs(groupId, forceAdvanceOnFail = false) {
         const ns = `group:${groupId}`;
         const queue = this._pendingDecryptMsgs.get(ns);
         if (!queue || queue.length === 0)
             return;
         this._pendingDecryptMsgs.set(ns, []);
         const stillPending = [];
+        let forceAdvancedAny = false;
         for (const msg of queue) {
             try {
                 const decrypted = await this._decryptGroupMessage(msg);
                 const payload = isJsonObject(msg.payload) ? msg.payload : null;
                 if (payload?.type === 'e2ee.group_encrypted' && !decrypted.e2ee) {
-                    stillPending.push(msg);
+                    if (forceAdvanceOnFail) {
+                        // recovery 真的失败：强制推进 seq tracker + 发 undecryptable + ack
+                        this._clientLog.info(`group recovery give up: group=${groupId} seq=${String(msg.seq ?? '')} → force advance + publish undecryptable`);
+                        const seq = msg.seq;
+                        if (seq !== undefined && seq !== null) {
+                            this._seqTracker.onMessageSeq(ns, seq);
+                            this._saveSeqTrackerState();
+                            forceAdvancedAny = true;
+                        }
+                        await this._publishAppEvent('group.message_undecryptable', {
+                            message_id: msg.message_id,
+                            group_id: groupId,
+                            from: msg.from,
+                            seq,
+                            timestamp: msg.timestamp,
+                            _decrypt_error: 'epoch recovery failed',
+                        });
+                    }
+                    else {
+                        stillPending.push(msg);
+                    }
                     continue;
                 }
                 const seq = msg.seq;
                 if (seq !== undefined && seq !== null) {
+                    // 推进 seq tracker（之前 push/pull 失败时没推进）
+                    this._seqTracker.onMessageSeq(ns, seq);
+                    this._saveSeqTrackerState();
                     await this._publishOrderedMessage('group.message_created', ns, seq, decrypted);
                 }
                 else {
@@ -3250,6 +3408,18 @@ export class AUNClient {
                 stillPending.push(msg);
             }
         }
+        // 强制推进有变更时，按 contig auto-ack
+        if (forceAdvancedAny) {
+            const contig = this._seqTracker.getContiguousSeq(ns);
+            if (contig > 0) {
+                this._transport.call('group.ack_messages', {
+                    group_id: groupId,
+                    msg_seq: contig,
+                    device_id: this._deviceId,
+                    slot_id: this._slotId,
+                }).catch((e) => { this._clientLog.debug(`group recovery force-advance ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+            }
+        }
         const queuedDuringRetry = this._pendingDecryptMsgs.get(ns) ?? [];
         const mergedPending = [...stillPending, ...queuedDuringRetry].slice(-PENDING_DECRYPT_LIMIT);
         if (mergedPending.length)
@@ -3257,6 +3427,28 @@ export class AUNClient {
         else
             this._pendingDecryptMsgs.delete(ns);
     }
+    /**
+     * recovery 兜底定时：N 秒后如果 pending queue 仍有未解开消息，强制推进 cursor。
+     * 同一 group 短时间内只调度一次。
+     */
+    _recoveryTimeoutScheduled = new Map();
+    _scheduleRecoveryTimeout(groupId, timeoutMs = 30000) {
+        if (!groupId)
+            return;
+        const now = Date.now();
+        const last = this._recoveryTimeoutScheduled.get(groupId) ?? 0;
+        if (last && (last + timeoutMs) > now)
+            return;
+        this._recoveryTimeoutScheduled.set(groupId, now);
+        setTimeout(() => {
+            const ns = `group:${groupId}`;
+            const queue = this._pendingDecryptMsgs.get(ns);
+            if (!queue || queue.length === 0)
+                return;
+            this._clientLog.info(`group recovery timeout: group=${groupId} → force advance`);
+            this._retryPendingDecryptMsgs(groupId, true).catch((exc) => this._clientLog.warn(`group ${groupId} recovery timeout retry failed: ${formatCaughtError(exc)}`));
+        }, timeoutMs).unref?.();
+    }
     _scheduleRetryPendingDecryptMsgs(groupId) {
         if (!groupId || !this._pendingDecryptMsgs.has(`group:${groupId}`))
             return;
@@ -3963,6 +4155,11 @@ export class AUNClient {
         const groupId = String(payload.group_id ?? '').trim();
         if (!groupId)
             return false;
+        // 历史群（不在当前 session 活跃列表）：跳过 RPC 验证，只做本地 handle_incoming
+        if (!this._groupSynced.has(groupId)) {
+            this._clientLog.debug(`skip RPC verify for inactive group: group=${groupId} rotation=${rotationId}`);
+            return true;
+        }
         const epoch = Number(payload.epoch ?? 0);
         if (!Number.isFinite(epoch) || epoch <= 0)
             return false;
@@ -4695,7 +4892,6 @@ export class AUNClient {
         this._pendingOrderedMsgs.clear();
         this._pendingDecryptMsgs.clear();
         this._groupSynced.clear();
-        this._p2pSynced = false;
     }
     _refreshSeqTrackerContext() {
         const nextContext = this._currentSeqTrackerContext();
@@ -4707,7 +4903,6 @@ export class AUNClient {
         this._pendingOrderedMsgs.clear();
         this._pendingDecryptMsgs.clear();
         this._groupSynced.clear();
-        this._p2pSynced = false;
         this._seqTrackerContext = nextContext;
     }
     /** 将 SeqTracker 状态保存到 keystore */
@@ -4796,6 +4991,9 @@ export class AUNClient {
         this._gatewayUrl = gatewayUrl;
         this._slotId = String(params.slot_id ?? '');
         this._connectDeliveryMode = { ...(params.delivery_mode ?? this._connectDeliveryMode) };
+        const extraInfo = (params.extra_info && typeof params.extra_info === 'object' && !Array.isArray(params.extra_info))
+            ? params.extra_info
+            : undefined;
         const prevState = this._state;
         this._auth.setInstanceContext({ deviceId: this._deviceId, slotId: this._slotId });
         this._state = 'connecting';
@@ -4814,6 +5012,9 @@ export class AUNClient {
                     deviceId: this._deviceId,
                     slotId: this._slotId,
                     deliveryMode: this._connectDeliveryMode,
+                    connectionKind: String(params.connection_kind ?? 'long'),
+                    shortTtlMs: Number(params.short_ttl_ms ?? 0),
+                    extraInfo,
                 });
                 if (isJsonObject(authContext)) {
                     const auth = authContext;
@@ -4827,17 +5028,27 @@ export class AUNClient {
                             this._sessionParams.access_token = String(auth.token ?? params.access_token ?? '');
                         }
                     }
+                    if (isJsonObject(auth.hello) && 'heartbeat_interval' in auth.hello) {
+                        this._applyServerHeartbeatInterval(auth.hello.heartbeat_interval, 'auth');
+                    }
                 }
             }
             else {
-                await this._auth.initializeWithToken(this._transport, challenge, String(params.access_token), {
+                const hello = await this._auth.initializeWithToken(this._transport, challenge, String(params.access_token), {
                     deviceId: this._deviceId,
                     slotId: this._slotId,
                     deliveryMode: this._connectDeliveryMode,
+                    connectionKind: String(params.connection_kind ?? 'long'),
+                    shortTtlMs: Number(params.short_ttl_ms ?? 0),
+                    extraInfo,
                 });
                 this._syncIdentityAfterConnect(String(params.access_token));
+                if (isJsonObject(hello) && 'heartbeat_interval' in hello) {
+                    this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
+                }
             }
             this._state = 'connected';
+            this._connectedAt = Date.now();
             this._clientLog.debug(`auth complete, connection ready: aid=${this._aid ?? ''}, gateway=${gatewayUrl}`);
             await this._dispatcher.publish('connection.state', { state: this._state, gateway: gatewayUrl });
             // auth 阶段 aid 可能被 identity 覆盖（上方 this._aid = identity.aid）；
@@ -4854,6 +5065,11 @@ export class AUNClient {
             catch (exc) {
                 this._clientLog.warn(`prekey upload failed: ${formatCaughtError(exc)}`);
             }
+            // connect/reconnect 成功后自动触发一次 P2P message.pull，补齐离线期间积压
+            // 群消息按惰性触发，不在此处主动 pull
+            void this._fillP2pGap().catch((exc) => {
+                this._clientLog.warn(`schedule post-connect P2P gap fill failed: ${formatCaughtError(exc)}`);
+            });
             this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl}, aid=${this._aid ?? ''}`);
         }
         catch (err) {
@@ -4940,16 +5156,29 @@ export class AUNClient {
         if ('timeouts' in request && request.timeouts != null && !isJsonObject(request.timeouts)) {
             throw new ValidationError('timeouts must be a dict');
         }
+        // 长短连接参数校验
+        const connectionKind = String(request.connection_kind ?? 'long');
+        if (connectionKind !== 'long' && connectionKind !== 'short') {
+            throw new ValidationError(`connection_kind must be "long" or "short", got "${connectionKind}"`);
+        }
+        request.connection_kind = connectionKind;
+        const shortTtlMs = Number(request.short_ttl_ms ?? 0);
+        if (!Number.isFinite(shortTtlMs) || shortTtlMs < 0 || Math.floor(shortTtlMs) !== shortTtlMs) {
+            throw new ValidationError('short_ttl_ms must be a non-negative integer');
+        }
+        request.short_ttl_ms = connectionKind === 'short' ? shortTtlMs : 0;
         return request;
     }
     /** 从参数构建会话选项 */
     _buildSessionOptions(params) {
+        const connectionKind = String(params.connection_kind ?? 'long');
         const options = {
             auto_reconnect: DEFAULT_SESSION_OPTIONS.auto_reconnect,
             heartbeat_interval: DEFAULT_SESSION_OPTIONS.heartbeat_interval,
             token_refresh_before: DEFAULT_SESSION_OPTIONS.token_refresh_before,
             retry: { ...DEFAULT_SESSION_OPTIONS.retry },
             timeouts: { ...DEFAULT_SESSION_OPTIONS.timeouts },
+            connection_kind: connectionKind,
         };
         if ('auto_reconnect' in params)
             options.auto_reconnect = Boolean(params.auto_reconnect);
@@ -4968,8 +5197,12 @@ export class AUNClient {
     // ── 内部：后台任务 ────────────────────────────────────────
     /** 启动所有后台任务 */
     _startBackgroundTasks() {
-        this._startHeartbeatTask();
-        this._startTokenRefreshTask();
+        // 短连接不启动 heartbeat 与 token 刷新（生命周期短，不需要长期会话维护）；
+        // auto_reconnect 仍允许，由 _sessionOptions.auto_reconnect 决定
+        if (this._sessionOptions.connection_kind !== 'short') {
+            this._startHeartbeatTask();
+            this._startTokenRefreshTask();
+        }
         this._startGroupEpochTasks();
     }
     /** 停止所有后台任务 */
@@ -5007,10 +5240,9 @@ export class AUNClient {
     _startHeartbeatTask() {
         if (this._heartbeatTimer !== null)
             return;
-        const rawIntervalSeconds = Number(this._sessionOptions.heartbeat_interval ?? DEFAULT_SESSION_OPTIONS.heartbeat_interval);
-        if (!Number.isFinite(rawIntervalSeconds) || rawIntervalSeconds <= 0)
+        const interval = clampHeartbeatInterval(this._sessionOptions.heartbeat_interval ?? DEFAULT_SESSION_OPTIONS.heartbeat_interval);
+        if (interval <= 0)
             return;
-        const interval = Math.max(rawIntervalSeconds, 30) * 1000;
         // M25: 把连续失败阈值从 3 次收窄到 2 次。既能容忍一次网络抖动/GC 暂停，
         // 又把半开连接的检测延迟从 3 个心跳周期降到 2 个。
         // 真正的 socket 死亡由 ws.on('close') 立即触发 _handleTransportDisconnect，
@@ -5020,8 +5252,12 @@ export class AUNClient {
         this._heartbeatTimer = setInterval(() => {
             if (this._closing || this._state !== 'connected')
                 return;
-            this._transport.call('meta.ping', {}).then(() => {
+            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)}`);
@@ -5031,12 +5267,28 @@ export class AUNClient {
                     this._handleTransportDisconnect(exc instanceof Error ? exc : new Error(String(exc)));
                 }
             });
-        }, interval);
+        }, interval * 1000);
         // 允许 Node.js 进程在只剩定时器时退出
         if (this._heartbeatTimer && typeof this._heartbeatTimer === 'object' && 'unref' in this._heartbeatTimer) {
             this._heartbeatTimer.unref();
         }
     }
+    /** 服务端通过 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}`);
+        if (this._heartbeatTimer !== null) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
+        }
+        if (newInterval > 0 && this._state === 'connected' && !this._closing) {
+            this._startHeartbeatTask();
+        }
+    }
     /** 启动 token 刷新任务 */
     _startTokenRefreshTask() {
         if (this._tokenRefreshTimer !== null)
@@ -5191,23 +5443,18 @@ export class AUNClient {
         const prekeyId = this._extractConsumedPrekeyId(message);
         if (!prekeyId || this._state !== 'connected')
             return;
-        if (this._prekeyReplenished.has(prekeyId))
-            return;
-        // 同一时刻只允许一个 put_prekey inflight
-        if (this._prekeyReplenishInflight.size > 0)
+        // 只有活跃 prekey 被消费时才触发上传。历史 prekey 被消费不触发，避免上传风暴。
+        if (!this._activePrekeyId || prekeyId !== this._activePrekeyId)
             return;
-        this._prekeyReplenishInflight.add(prekeyId);
+        // 清空活跃标记，防止重复触发（新上传完成后会设新的 active）
+        this._activePrekeyId = '';
         void (async () => {
             try {
                 await this._uploadPrekey();
-                this._prekeyReplenished.add(prekeyId);
             }
             catch (exc) {
                 this._clientLog.warn(`replenish current prekey after consuming ${prekeyId} failed: ${formatCaughtError(exc)}`);
             }
-            finally {
-                this._prekeyReplenishInflight.delete(prekeyId);
-            }
         })();
     }
     /** 启动群组 epoch 相关后台任务 */
@@ -5291,13 +5538,34 @@ export class AUNClient {
     }
     // ── 内部：断线重连 ────────────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
-    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011]);
-    /** 处理服务端主动断开通知 event/gateway.disconnect */
-    _onGatewayDisconnect(data) {
-        const code = data?.code;
-        const reason = data?.reason ?? '';
-        this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}`);
+    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015]);
+    /** 处理服务端主动断开通知 event/gateway.disconnect。
+     *
+     * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。
+     * 透传到应用层可订阅事件 'gateway.disconnect'，方便业务定位被踢原因。
+     */
+    async _onGatewayDisconnect(data) {
+        const payload = (data && typeof data === 'object') ? data : {};
+        const code = payload.code;
+        const reason = payload.reason ?? '';
+        const detail = (payload.detail && typeof payload.detail === 'object' && !Array.isArray(payload.detail))
+            ? payload.detail
+            : {};
+        this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}, detail=${JSON.stringify(detail)}`);
         this._serverKicked = true;
+        // 缓存最近一次 disconnect 信息，让后续 connection.state(terminal_failed) 也能带 detail
+        this._lastDisconnectInfo = { code, reason, detail };
+        // 透传给应用层订阅者
+        try {
+            await this._dispatcher.publish('gateway.disconnect', {
+                code,
+                reason,
+                detail,
+            });
+        }
+        catch (exc) {
+            this._clientLog.debug(`publish gateway.disconnect failed: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
     }
     /** 传输层断线回调 */
     async _handleTransportDisconnect(error, closeCode) {
@@ -5319,9 +5587,18 @@ export class AUNClient {
             this._state = 'terminal_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
             this._clientLog.warn(`suppressing auto-reconnect: ${reason}`);
-            await this._dispatcher.publish('connection.state', {
+            const disconnectInfo = this._lastDisconnectInfo ?? {};
+            const eventPayload = {
                 state: this._state, error, reason,
-            });
+            };
+            // 把服务端附带的结构化 detail（如配额超限信息）也带给应用层
+            if (disconnectInfo.detail && Object.keys(disconnectInfo.detail).length > 0) {
+                eventPayload.detail = disconnectInfo.detail;
+            }
+            if (disconnectInfo.code !== undefined && disconnectInfo.code !== null) {
+                eventPayload.code = disconnectInfo.code;
+            }
+            await this._dispatcher.publish('connection.state', eventPayload);
             return;
         }
         // 1000 = 正常关闭, 1006 = 网络异常断开（无 close frame），其他 code = 服务端主动关闭