@agentunion/fastaun-browser 0.2.18 → 0.2.20

package/dist/client.js

@@ -87,7 +87,7 @@ const DEFAULT_SESSION_OPTIONS = {
     },
     timeouts: {
         connect: 5.0,
-        call: 10.0,
+        call: 35.0,
         http: 30.0,
     },
 };
@@ -99,6 +99,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 = 35;
 const NON_IDEMPOTENT_METHODS = new Set([
@@ -321,6 +335,7 @@ export class AUNClient {
     _gatewayUrl = null;
     _deviceId;
     _slotId;
+    _connectedAt = 0;
     _connectDeliveryMode;
     _defaultConnectDeliveryMode;
     _closing = false;
@@ -343,6 +358,8 @@ export class AUNClient {
     _certCache = new Map();
     _prekeyReplenishInflight = new Set();
     _prekeyReplenished = new Set();
+    // 当前活跃 prekey：只有这个 prekey 被消费时才触发 replenish 上传
+    _activePrekeyId = '';
     _peerPrekeysCache = new Map();
     // 后台任务 handle（浏览器 setInterval/setTimeout）
     _heartbeatTimer = null;
@@ -352,6 +369,17 @@ export class AUNClient {
     _groupEpochCleanupTimer = null;
     _groupEpochRotateTimer = null;
     _cacheCleanupTimer = null;
+    /**
+     * 本地 agent.md 内容对应的 etag（quoted sha256 hex，与服务端 _agent_md_etag 一致）。
+     *
+     * 浏览器无法直接读本地文件，因此 API 不接收 path，而是接收 markdown 字符串：
+     * 应用层（如 `<input type=file>`）读出文本后调用 setLocalAgentMdContent() 设置。
+     * 用于跟服务端 RPC 注入的 _meta.agent_md_etag 比对，触发"本地未发布到服务端"或
+     * "服务端版本更新"的 UI 提示。
+     */
+    _localAgentMdEtag = '';
+    /** gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。 */
+    _remoteAgentMdEtag = '';
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -370,14 +398,17 @@ export class AUNClient {
     _groupEpochRotationRetryTimers = new Map();
     /** Lazy group sync：首次发送群消息前自动拉取历史 */
     _groupSynced = new Set();
-    /** Lazy P2P sync：首次发送 P2P 消息前自动拉取历史 */
-    _p2pSynced = false;
     /** gap fill 来源标记：true 表示当前正在补洞（pull 触发），false 表示非补洞 */
     _gapFillActive = false;
     // 重连相关
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
+    /**
+     * 缓存最近一次服务端 gateway.disconnect 信息（含 code/reason/detail），
+     * 让后续 connection.state(terminal_failed) 也能携带 detail（如配额超限信息）。
+     */
+    _lastDisconnectInfo = null;
     // Logger（per-client 单例 + 各模块子 logger）
     _logger;
     _clientLog;
@@ -430,6 +461,7 @@ export class AUNClient {
             timeout: DEFAULT_SESSION_OPTIONS.timeouts.call,
             onDisconnect: (error, closeCode) => this._handleTransportDisconnect(error, closeCode),
         });
+        this._transport.setMetaObserver((meta) => this._observeRpcMeta(meta));
         this._e2ee = new E2EEManager({
             identityFn: () => this._identity ?? {},
             deviceIdFn: () => this._deviceId,
@@ -492,14 +524,66 @@ export class AUNClient {
             });
         }
         // 服务端主动断开通知：记录日志并标记不重连
-        this._dispatcher.subscribe('_raw.gateway.disconnect', (data) => {
-            this._onGatewayDisconnect(data);
+        this._dispatcher.subscribe('_raw.gateway.disconnect', async (data) => {
+            await this._onGatewayDisconnect(data);
         });
     }
     // ── 属性 ──────────────────────────────────────────
     get aid() {
         return this._aid;
     }
+    /**
+     * 设置本地 agent.md 内容并一次性计算 etag（quoted sha256，与服务端一致）。
+     *
+     * 浏览器环境无法直接读本地文件，应用应通过 `<input type=file>` 等方式读出 markdown
+     * 文本后调用本方法。content 为空字符串时清除本地 etag。失败不抛异常（debug 日志记录），
+     * 应用可读 getLocalAgentMdEtag() 返回值或本方法返回值判断。
+     *
+     * 返回当前 etag（quoted hex 或空串）。
+     */
+    async setLocalAgentMdContent(content) {
+        const text = String(content ?? '');
+        if (text.length === 0) {
+            this._localAgentMdEtag = '';
+            return '';
+        }
+        try {
+            const data = new TextEncoder().encode(text);
+            const buf = await crypto.subtle.digest('SHA-256', data);
+            const bytes = new Uint8Array(buf);
+            let hex = '';
+            for (let i = 0; i < bytes.length; i++) {
+                hex += bytes[i].toString(16).padStart(2, '0');
+            }
+            this._localAgentMdEtag = `"${hex}"`;
+        }
+        catch (exc) {
+            this._clientLog.warn(`setLocalAgentMdContent sha256 failed: ${String(exc)}`);
+            this._localAgentMdEtag = '';
+        }
+        return this._localAgentMdEtag;
+    }
+    /** 返回 setLocalAgentMdContent 计算的 etag；未设置或计算失败时返回空串。 */
+    getLocalAgentMdEtag() {
+        return this._localAgentMdEtag;
+    }
+    /**
+     * 返回 gateway 在最近一次 RPC envelope._meta 注入的服务端 agent.md etag。
+     *
+     * 未收到过则为空串；不阻塞调用，纯内存读。
+     */
+    getRemoteAgentMdEtag() {
+        return this._remoteAgentMdEtag;
+    }
+    /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
+    _observeRpcMeta(meta) {
+        if (!isJsonObject(meta))
+            return;
+        const etag = String(meta.agent_md_etag ?? '').trim();
+        if (etag) {
+            this._remoteAgentMdEtag = etag;
+        }
+    }
     get state() {
         return this._state;
     }
@@ -714,6 +798,7 @@ export class AUNClient {
                 return this._sendEncrypted(p);
             }
             // encrypt=false：明文走通用 RPC 路径；protected_headers/headers 是信封元数据，加密与否都保留
+            this._maybeAppendEchoTraceSend(p);
         }
         // 自动加密：group.send 默认加密（encrypt 默认 true）
         if (method === 'group.send') {
@@ -722,6 +807,7 @@ export class AUNClient {
             if (encrypt) {
                 return this._sendGroupEncrypted(p);
             }
+            this._maybeAppendEchoTraceSend(p);
         }
         if (method === 'group.thought.put') {
             const encrypt = p.encrypt !== undefined ? p.encrypt : true;
@@ -788,7 +874,6 @@ export class AUNClient {
         if (method === 'group.pull' && isJsonObject(result)) {
             const r = result;
             const messages = r.messages;
-            // 先保存原始消息（解密前），用于喂 SeqTracker（与 P2P message.pull 路径对齐）
             const rawMessages = (Array.isArray(messages) ? messages : []).filter(isJsonObject);
             if (rawMessages.length) {
                 r.messages = await this._decryptGroupMessages(rawMessages);
@@ -796,13 +881,28 @@ export class AUNClient {
             const gid = (p.group_id ?? '');
             if (gid) {
                 const ns = `group:${gid}`;
-                // ⚠️ 使用原始消息（rawMessages）喂 SeqTracker，与 P2P message.pull 路径一致
-                if (rawMessages.length) {
-                    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) {
+                    // 仅用解密成功的消息推进 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);
@@ -815,9 +915,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,
@@ -826,6 +926,10 @@ export class AUNClient {
                         slot_id: this._slotId,
                     }).catch((e) => { this._clientLog.warn('group.pull auto-ack failed: group=' + gid, e); });
                 }
+                // 有解密失败时调度 recovery 兜底定时
+                if (failedCount > 0) {
+                    this._scheduleRecoveryTimeout(gid);
+                }
             }
         }
         if (method === 'group.thought.get' && isJsonObject(result)) {
@@ -920,12 +1024,26 @@ 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;
-            // 推送路径收到 P2P 消息 → 标记已同步，后续发送无需再 lazySyncP2p
-            this._p2pSynced = true;
             if (seq !== undefined && seq !== null && this._aid) {
                 const ns = `p2p:${this._aid}`;
                 const needPull = this._seqTracker.onMessageSeq(ns, seq);
@@ -1004,8 +1122,12 @@ export class AUNClient {
                 return;
             }
             const decrypted = await this._decryptGroupMessage(msg);
-            // 只有带 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) {
@@ -1023,10 +1145,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 ?? null,
                     group_id: groupId,
@@ -1349,8 +1473,61 @@ 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) && payload._agent_md === undefined) {
+                    payload._agent_md = {
+                        local_etag: localEtag,
+                        remote_etag: remoteEtag,
+                    };
+                }
+            }
+            catch (exc) {
+                this._clientLog.debug(`agent_md etag inject skipped: ${String(exc)}`);
+            }
+        }
         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;
@@ -1864,10 +2041,8 @@ export class AUNClient {
             }
             const persistRequired = Boolean(params.persist_required || params.durable);
             const protectedHeaders = this._protectedHeadersFromParams(params);
-            // Lazy P2P sync：首次发送前自动拉取历史，避免重连后 seq 空洞
-            if (!this._p2pSynced) {
-                await this._lazySyncP2p();
-            }
+            // 惰性 P2P 同步由 connect/reconnect 完成后的 _fillP2pGap 异步触发，
+            // 不再在 send 路径上 await（与 C++ FillP2PGap 行为对齐，避免阻塞用户发送）。
             // 内部发送逻辑，refreshPeerMaterial=true 时强制清缓存重新拉取对端材料
             const sendAttempt = async (refreshPeerMaterial = false) => {
                 const recipientPrekeys = refreshPeerMaterial
@@ -1876,20 +2051,13 @@ export class AUNClient {
                 const selfSyncCopies = await this._buildSelfSyncCopies({
                     logicalToAid: toAid, payload, messageId, 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, payload, messageId, timestamp,
@@ -1932,63 +2100,6 @@ export class AUNClient {
             throw err;
         }
     }
-    /**
-     * 首次发送 P2P 消息前懒拉取历史消息，同步 seqTracker 避免空洞。
-     * 只在本连接周期内执行一次。
-     */
-    async _lazySyncP2p() {
-        this._p2pSynced = true;
-        if (!this._aid)
-            return;
-        const ns = `p2p:${this._aid}`;
-        const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        try {
-            const result = await this._transport.call('message.pull', {
-                after_seq: afterSeq,
-                limit: 200,
-            });
-            if (isJsonObject(result)) {
-                const messages = result.messages;
-                if (Array.isArray(messages) && messages.length > 0) {
-                    this._seqTracker.onPullResult(ns, messages.filter(isJsonObject));
-                    this._saveSeqTrackerState();
-                }
-            }
-        }
-        catch (exc) {
-            this._clientLog.warn(`lazySyncP2p failed:${String(exc)}`);
-        }
-    }
-    async _sendEncryptedSingle(opts) {
-        let prekey = opts.prekey;
-        if (prekey === undefined) {
-            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] = await this._encryptCopyPayload({
-            logicalToAid: opts.toAid,
-            payload: opts.payload,
-            peerCertPem,
-            prekey,
-            messageId: opts.messageId,
-            timestamp: opts.timestamp,
-            protectedHeaders: opts.protectedHeaders,
-        });
-        await this._ensureEncryptResult(opts.toAid, encryptResult);
-        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 this._transport.call('message.send', sendParams);
-    }
     async _buildRecipientDeviceCopies(opts) {
         const recipientCopies = [];
         const certCache = new Map();
@@ -2731,23 +2842,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 真的失败：强制推进 + 发 undecryptable
+                        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 {
@@ -2758,6 +2893,17 @@ export class AUNClient {
                 stillPending.push(msg);
             }
         }
+        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.warn('group recovery force-advance ack failed: group=' + groupId, e); });
+            }
+        }
         const queuedDuringRetry = this._pendingDecryptMsgs.get(ns) ?? [];
         const mergedPending = [...stillPending, ...queuedDuringRetry].slice(-PENDING_DECRYPT_LIMIT);
         if (mergedPending.length)
@@ -2765,6 +2911,25 @@ export class AUNClient {
         else
             this._pendingDecryptMsgs.delete(ns);
     }
+    // recovery 兜底定时去重：每个 group 在 30s 内最多调度一次"超时强制推进"任务
+    _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._safeAsync(this._retryPendingDecryptMsgs(groupId, true));
+        }, timeoutMs);
+    }
     _scheduleRetryPendingDecryptMsgs(groupId) {
         if (!groupId || !this._pendingDecryptMsgs.has(`group:${groupId}`))
             return;
@@ -3395,11 +3560,31 @@ export class AUNClient {
         let result = null;
         try {
             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 = await 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 = await 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;
                 }
@@ -3681,6 +3866,8 @@ export class AUNClient {
     async _uploadPrekey() {
         const prekeyMaterial = await 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 };
     }
     /** 确保发送方证书在本地可用且未过期 */
@@ -3895,6 +4082,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;
@@ -4679,6 +4871,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: params.extra_info,
                     });
                     if (isJsonObject(authContext)) {
                         const auth = authContext;
@@ -4690,15 +4885,24 @@ 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: params.extra_info,
                     });
                     await this._syncIdentityAfterConnect(String(params.access_token));
+                    if (isJsonObject(hello) && 'heartbeat_interval' in hello) {
+                        this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
+                    }
                 }
             }
             catch (err) {
@@ -4711,11 +4915,11 @@ export class AUNClient {
                 throw err;
             }
             this._state = 'connected';
+            this._connectedAt = Date.now();
             await this._dispatcher.publish('connection.state', {
                 state: this._state,
                 gateway: gatewayUrl,
             });
-            // auth 阶段 aid 可能被 identity 覆盖；若 context 发生变化，重新 refresh + restore。
             if (this._seqTrackerContext !== this._currentSeqTrackerContext()) {
                 this._refreshSeqTrackerContext();
                 await this._restoreSeqTrackerState();
@@ -4728,6 +4932,9 @@ export class AUNClient {
             catch (exc) {
                 this._clientLog.warn(`prekey upload failed:${String(exc)}`);
             }
+            // connect/reconnect 成功后自动触发一次 P2P message.pull，补齐离线期间积压
+            // 群消息按惰性触发，不在此处主动 pull
+            this._safeAsync(this._fillP2pGap());
             this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? '-'}`);
         }
         catch (err) {
@@ -4813,15 +5020,38 @@ export class AUNClient {
         if (request.timeouts !== undefined && !isJsonObject(request.timeouts)) {
             throw new ValidationError('timeouts must be an object');
         }
+        // 长短连接选项：默认 long，向后兼容
+        const kindRaw = request.connection_kind;
+        if (kindRaw == null) {
+            request.connection_kind = 'long';
+        }
+        else {
+            request.connection_kind = String(kindRaw).trim().toLowerCase();
+        }
+        if (request.connection_kind !== 'long' && request.connection_kind !== 'short') {
+            throw new ValidationError("connection_kind must be 'long' or 'short'");
+        }
+        try {
+            request.short_ttl_ms = Math.max(0, Math.floor(Number(request.short_ttl_ms) || 0));
+        }
+        catch {
+            throw new ValidationError('short_ttl_ms must be a non-negative integer');
+        }
+        if (request.connection_kind !== 'short') {
+            request.short_ttl_ms = 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,
+            short_ttl_ms: Number(params.short_ttl_ms ?? 0),
         };
         if ('auto_reconnect' in params) {
             options.auto_reconnect = Boolean(params.auto_reconnect);
@@ -4842,8 +5072,12 @@ export class AUNClient {
     }
     // ── 内部：后台任务 ────────────────────────────────
     _startBackgroundTasks() {
-        this._startHeartbeat();
-        this._startTokenRefresh();
+        // 短连接不启动 heartbeat 与 token 刷新（生命周期短，不需要长期会话维护）；
+        // auto_reconnect 仍允许，由 _sessionOptions.auto_reconnect 决定
+        if (this._sessionOptions?.connection_kind !== 'short') {
+            this._startHeartbeat();
+            this._startTokenRefresh();
+        }
         this._startPrekeyRefresh();
         this._startGroupEpochTasks();
     }
@@ -4881,10 +5115,9 @@ export class AUNClient {
     _startHeartbeat() {
         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 个，避免 RPC 长时间挂起。
         // 真正的 socket 死亡由 ws.on('close') 立即触发 _handleTransportDisconnect，
@@ -4895,8 +5128,12 @@ export class AUNClient {
             if (this._state !== 'connected' || this._closing)
                 return;
             try {
-                await this._transport.call('meta.ping', {});
+                const pong = await this._transport.call('meta.ping', {});
                 consecutiveFailures = 0;
+                // 服务端可在 pong 中下发新的 heartbeat_interval（秒，0=关闭）
+                if (isJsonObject(pong) && 'heartbeat_interval' in pong) {
+                    this._applyServerHeartbeatInterval(pong.heartbeat_interval, 'pong');
+                }
             }
             catch (exc) {
                 consecutiveFailures++;
@@ -4907,7 +5144,24 @@ export class AUNClient {
                     this._handleTransportDisconnect(exc instanceof Error ? exc : new Error(String(exc)));
                 }
             }
-        }, interval);
+        }, interval * 1000);
+    }
+    /** 服务端通过 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._startHeartbeat();
+        }
     }
     /** Token 刷新定时器 */
     _startTokenRefresh() {
@@ -5107,22 +5361,17 @@ 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 = '';
         this._safeAsync((async () => {
             try {
                 await this._uploadPrekey();
-                this._prekeyReplenished.add(prekeyId);
             }
             catch (exc) {
-                this._clientLog.warn(`consume prekey ${prekeyId} then replenish current prekey failed: ${String(exc)}`);
-            }
-            finally {
-                this._prekeyReplenishInflight.delete(prekeyId);
+                this._clientLog.warn(`replenish current prekey after consuming ${prekeyId} failed: ${String(exc)}`);
             }
         })());
     }
@@ -5191,13 +5440,28 @@ 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 obj = (data && typeof data === 'object') ? data : {};
+        const code = obj.code;
+        const reason = obj.reason ?? '';
+        const detail = (obj.detail && typeof obj.detail === 'object') ? obj.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?.message ?? exc}`);
+        }
     }
     async _handleTransportDisconnect(error, closeCode) {
         if (this._closing || this._state === 'closed')
@@ -5218,9 +5482,19 @@ export class AUNClient {
             this._state = 'terminal_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
             this._clientLog.warn(`suppress auto-reconnect: ${reason}`);
-            await this._dispatcher.publish('connection.state', {
+            const disconnectInfo = this._lastDisconnectInfo ?? {};
+            const eventPayload = {
                 state: this._state, error, reason,
-            });
+            };
+            // 把服务端附带的结构化 detail（如配额超限信息）也带给应用层
+            const detail = disconnectInfo.detail;
+            if (detail && typeof detail === 'object' && Object.keys(detail).length > 0) {
+                eventPayload.detail = 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 = 服务端主动关闭
@@ -5526,7 +5800,6 @@ export class AUNClient {
         this._pendingOrderedMsgs.clear();
         this._pendingDecryptMsgs.clear();
         this._groupSynced.clear();
-        this._p2pSynced = false;
     }
     _refreshSeqTrackerContext() {
         const nextContext = this._currentSeqTrackerContext();
@@ -5538,7 +5811,6 @@ export class AUNClient {
         this._pendingOrderedMsgs.clear();
         this._pendingDecryptMsgs.clear();
         this._groupSynced.clear();
-        this._p2pSynced = false;
         this._seqTrackerContext = nextContext;
     }
     /** 将 SeqTracker 状态保存到 keystore */