@agentunion/fastaun-browser 0.2.13 → 0.2.14

package/dist/client.js

@@ -59,6 +59,9 @@ const SIGNED_METHODS = new Set([
     'group.transfer_owner', 'group.review_join_request',
     'group.batch_review_join_request',
     'group.request_join', 'group.use_invite_code',
+    'group.thought.put',
+    'message.thought.put',
+    'group.set_settings',
     'group.resources.put', 'group.resources.update',
     'group.resources.delete', 'group.resources.request_add',
     'group.resources.direct_add', 'group.resources.approve_request',
@@ -84,6 +87,21 @@ const RECONNECT_MIN_BASE_DELAY_SECONDS = 1.0;
 const RECONNECT_MAX_BASE_DELAY_SECONDS = 64.0;
 const GROUP_ROTATION_LEASE_MS = 120_000;
 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;
+// P1-23: 非幂等方法使用更长超时（35s），避免 SDK 10s 超时 < gateway 30s 处理时间
+const NON_IDEMPOTENT_TIMEOUT = 35;
+const NON_IDEMPOTENT_METHODS = new Set([
+    'message.send', 'group.send', 'group.create', 'group.invite',
+    'group.kick', 'group.remove_member', 'group.leave', 'group.dissolve',
+    'group.update_name', 'group.update_avatar', 'group.update_announcement',
+    'group.update_settings', 'group.rotate_epoch',
+    'storage.upload', 'storage.complete_upload', 'storage.delete',
+    'auth.create_aid', 'auth.renew_cert', 'auth.rekey',
+    'message.thought.put', 'group.thought.put',
+    'group.add_member',
+]);
 function clampReconnectDelaySeconds(value, fallback, upper = RECONNECT_MAX_BASE_DELAY_SECONDS) {
     const parsed = Number(value);
     const seconds = Number.isFinite(parsed) ? parsed : fallback;
@@ -269,8 +287,10 @@ export class AUNClient {
     _seqTrackerContext = null;
     /** 补洞去重：已完成/进行中的 key 集合，防止重复 pull 同一区间 */
     _gapFillDone = new Set();
-    /** 推送路径已分发的 seq 集合（按命名空间），补洞路径 publish 前检查以避免重复分发 */
+    /** 已发布到应用层的 seq 集合（按命名空间），补洞路径 publish 前检查以避免重复分发 */
     _pushedSeqs = new Map();
+    /** 已解密但因 seq 空洞暂缓发布的应用层消息（按 namespace -> seq） */
+    _pendingOrderedMsgs = new Map();
     _pendingDecryptMsgs = new Map();
     _groupEpochRotationInflight = new Set();
     _groupEpochRecoveryInflight = new Map();
@@ -343,7 +363,7 @@ export class AUNClient {
             this._onRawGroupChanged(data);
         });
         // 其他事件直接透传
-        for (const evt of ['message.recalled', 'message.ack']) {
+        for (const evt of ['message.recalled', 'message.ack', 'storage.object_changed']) {
             this._dispatcher.subscribe(`_raw.${evt}`, (data) => {
                 this._dispatcher.publish(evt, data);
             });
@@ -522,11 +542,31 @@ export class AUNClient {
                 return this._sendGroupEncrypted(p);
             }
         }
+        if (method === 'group.thought.put') {
+            const encrypt = p.encrypt !== undefined ? p.encrypt : true;
+            delete p.encrypt;
+            if (!encrypt) {
+                throw new ValidationError('group.thought.put requires encrypt=true');
+            }
+            return this._putGroupThoughtEncrypted(p);
+        }
+        if (method === 'message.thought.put') {
+            const encrypt = p.encrypt !== undefined ? p.encrypt : true;
+            delete p.encrypt;
+            if (!encrypt) {
+                throw new ValidationError('message.thought.put requires encrypt=true');
+            }
+            return this._putMessageThoughtEncrypted(p);
+        }
         // 关键操作自动附加客户端签名
         if (SIGNED_METHODS.has(method)) {
             await this._signClientOperation(method, p);
         }
-        const result = await this._transport.call(method, p);
+        // P1-23: 非幂等方法使用更长超时
+        const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT : undefined;
+        const result = callTimeout
+            ? await this._transport.call(method, p, callTimeout)
+            : await this._transport.call(method, p);
         // 自动解密：message.pull 返回的消息
         if (method === 'message.pull' && isJsonObject(result)) {
             const r = result;
@@ -560,6 +600,7 @@ export class AUNClient {
                     this._transport.call('message.ack', {
                         seq: contig,
                         device_id: this._deviceId,
+                        slot_id: this._slotId,
                     }).catch((e) => { console.warn('message.pull auto-ack 失败:', e); });
                 }
             }
@@ -608,6 +649,12 @@ export class AUNClient {
                 }
             }
         }
+        if (method === 'group.thought.get' && isJsonObject(result)) {
+            return this._decryptGroupThoughts(result);
+        }
+        if (method === 'message.thought.get' && isJsonObject(result)) {
+            return this._decryptMessageThoughts(result);
+        }
         // ── Group E2EE 自动编排 ────────────────────────────
         // ── Group E2EE 自动编排（必备能力，始终启用）────────
         {
@@ -639,7 +686,10 @@ export class AUNClient {
             const groupId = this._extractGroupIdFromResult(result) || String(p.group_id ?? '');
             if (groupId && this._membershipRotationChanged(method, result)) {
                 const expectedEpoch = this._membershipRotationExpectedEpoch(result);
-                this._safeAsync(this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, result), expectedEpoch));
+                // P0-12: await rotation 完成（带超时兜底），确保后续 group.send 使用新 epoch
+                const rotationPromise = this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, result), expectedEpoch);
+                const timeoutPromise = new Promise((resolve) => globalThis.setTimeout(resolve, 5000));
+                await Promise.race([rotationPromise, timeoutPromise]).catch((exc) => console.warn('membership RPC epoch rotation fallback failed:', exc));
             }
         }
         return result;
@@ -677,10 +727,13 @@ export class AUNClient {
     async _processAndPublishMessage(data) {
         try {
             if (!isJsonObject(data)) {
-                await this._dispatcher.publish('message.received', data);
+                await this._publishAppEvent('message.received', data);
                 return;
             }
             const msg = { ...data };
+            if (!this._messageTargetsCurrentInstance(msg)) {
+                return;
+            }
             // 拦截 P2P 传输的群组密钥分发/请求/响应消息
             if (await this._tryHandleGroupKeyMessage(msg)) {
                 return;
@@ -701,20 +754,20 @@ export class AUNClient {
                     this._transport.call('message.ack', {
                         seq: contig,
                         device_id: this._deviceId,
+                        slot_id: this._slotId,
                     }).catch((e) => { console.warn('P2P auto-ack 失败:', e); });
                 }
                 // 即时持久化 cursor，异常断连后不回退
                 this._saveSeqTrackerState();
             }
             const decrypted = await this._decryptSingleMessage(msg);
-            // 记录已推送的 seq，补洞路径据此去重
             if (seq !== undefined && seq !== null && this._aid) {
                 const ns = `p2p:${this._aid}`;
-                if (!this._pushedSeqs.has(ns))
-                    this._pushedSeqs.set(ns, new Set());
-                this._pushedSeqs.get(ns).add(seq);
+                await this._publishOrderedMessage('message.received', ns, seq, decrypted);
+            }
+            else {
+                await this._publishAppEvent('message.received', decrypted);
             }
-            await this._dispatcher.publish('message.received', decrypted);
         }
         catch (exc) {
             console.warn('消息解密失败:', exc);
@@ -730,7 +783,7 @@ export class AUNClient {
                     timestamp: (src.timestamp ?? null),
                     _decrypt_error: String(exc),
                 };
-                await this._dispatcher.publish('message.undecryptable', safeEvent);
+                await this._publishAppEvent('message.undecryptable', safeEvent);
             }
         }
     }
@@ -747,7 +800,7 @@ export class AUNClient {
     async _processAndPublishGroupMessage(data) {
         try {
             if (!isJsonObject(data)) {
-                await this._dispatcher.publish('group.message_created', data);
+                await this._publishAppEvent('group.message_created', data);
                 return;
             }
             const msg = { ...data };
@@ -783,19 +836,12 @@ export class AUNClient {
                 }
                 this._saveSeqTrackerState();
             }
-            // 记录已推送的 seq，补洞路径据此去重
-            if (groupId && seq !== undefined && seq !== null) {
-                const nsKey = `group:${groupId}`;
-                if (!this._pushedSeqs.has(nsKey))
-                    this._pushedSeqs.set(nsKey, new Set());
-                this._pushedSeqs.get(nsKey).add(seq);
-            }
             // R3: 解密失败 → 不 publish 密文给应用层，入 pending 队列 + 发 undecryptable 事件
             const payloadForCheck = isJsonObject(msg.payload) ? msg.payload : null;
             if (payloadForCheck?.type === 'e2ee.group_encrypted' && !decrypted.e2ee) {
                 if (groupId)
                     this._enqueuePendingDecrypt(groupId, msg);
-                await this._dispatcher.publish('group.message_undecryptable', {
+                await this._publishAppEvent('group.message_undecryptable', {
                     message_id: msg.message_id ?? null,
                     group_id: groupId,
                     from: msg.from ?? null,
@@ -805,7 +851,13 @@ export class AUNClient {
                 });
                 return;
             }
-            await this._dispatcher.publish('group.message_created', decrypted);
+            if (groupId && seq !== undefined && seq !== null) {
+                const nsKey = `group:${groupId}`;
+                await this._publishOrderedMessage('group.message_created', nsKey, seq, decrypted);
+            }
+            else {
+                await this._publishAppEvent('group.message_created', decrypted);
+            }
         }
         catch (exc) {
             console.warn('群消息解密失败:', exc);
@@ -820,7 +872,7 @@ export class AUNClient {
                     timestamp: (src.timestamp ?? null),
                     _decrypt_error: String(exc),
                 };
-                await this._dispatcher.publish('group.message_undecryptable', safeEvent);
+                await this._publishAppEvent('group.message_undecryptable', safeEvent);
             }
         }
     }
@@ -828,7 +880,7 @@ export class AUNClient {
     async _autoPullGroupMessages(notification) {
         const groupId = (notification.group_id ?? '');
         if (!groupId) {
-            await this._dispatcher.publish('group.message_created', notification);
+            await this._publishAppEvent('group.message_created', notification);
             return;
         }
         const ns = `group:${groupId}`;
@@ -844,15 +896,19 @@ export class AUNClient {
                 const messages = result.messages;
                 if (Array.isArray(messages)) {
                     // ⚠️ 不再重复调用 onPullResult：call('group.pull') 拦截器已在内部调用过一次
-                    // pushedSeqs 去重：跳过已通过推送路径分发的消息
                     const pushed = this._pushedSeqs.get(ns);
                     for (const msg of messages) {
                         if (isJsonObject(msg)) {
                             const s = msg.seq;
                             if (pushed && s !== undefined && s !== null && pushed.has(s)) {
-                                continue; // 已通过推送路径分发，跳过
+                                continue; // 已发布到应用层，跳过
+                            }
+                            if (s !== undefined && s !== null) {
+                                await this._publishOrderedMessage('group.message_created', ns, s, msg);
+                            }
+                            else {
+                                await this._publishAppEvent('group.message_created', msg);
                             }
-                            await this._dispatcher.publish('group.message_created', msg);
                         }
                     }
                     this._prunePushedSeqs(ns);
@@ -864,7 +920,7 @@ export class AUNClient {
             console.warn('自动 pull 群消息失败:', exc);
         }
         // pull 失败时仍透传原始通知
-        await this._dispatcher.publish('group.message_created', notification);
+        await this._publishAppEvent('group.message_created', notification);
     }
     /** 后台补齐群消息空洞 */
     async _fillGroupGap(groupId) {
@@ -873,10 +929,6 @@ export class AUNClient {
             return;
         const ns = `group:${groupId}`;
         const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        // 冷启动（seq=0）：服务端推送会带全量消息，SDK 不主动补洞避免重复拉取
-        if (afterSeq === 0) {
-            return;
-        }
         // 去重：同一 (group:id:after_seq) 在飞行中只补一次
         // S1: 使用 try/finally 保证无论成功失败都清理 dedupKey，避免旧实现只在异常路径清理
         // 导致成功后相同 afterSeq 再次出现空洞时被永久抑制。
@@ -902,7 +954,12 @@ export class AUNClient {
                             const s = msg.seq;
                             if (pushed && s !== undefined && s !== null && pushed.has(s))
                                 continue;
-                            await this._dispatcher.publish('group.message_created', msg);
+                            if (s !== undefined && s !== null) {
+                                await this._publishOrderedMessage('group.message_created', ns, s, msg);
+                            }
+                            else {
+                                await this._publishAppEvent('group.message_created', msg);
+                            }
                         }
                     }
                     this._prunePushedSeqs(ns);
@@ -925,10 +982,6 @@ export class AUNClient {
             return;
         const ns = `group_event:${groupId}`;
         const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        // 冷启动（seq=0）：服务端推送会带全量事件，SDK 不主动补洞避免重复拉取
-        if (afterSeq === 0) {
-            return;
-        }
         // 去重：同一 (group_evt:id:after_seq) 在飞行中只补一次
         // S1: 使用 try/finally 保证无论成功失败都清理 dedupKey
         const dedupKey = `group_evt:${groupId}:${afterSeq}`;
@@ -947,14 +1000,24 @@ export class AUNClient {
                 const events = result.events;
                 if (Array.isArray(events)) {
                     this._seqTracker.onPullResult(ns, events.filter(isJsonObject));
+                    const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+                    const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
+                    if (serverAck > 0) {
+                        const contigBefore = this._seqTracker.getContiguousSeq(ns);
+                        if (contigBefore < serverAck) {
+                            console.info('[aun_core] group.pull_events retention-floor 推进: ns=' + ns + ' contiguous=' + contigBefore + ' -> cursor.current_seq=' + serverAck);
+                            this._seqTracker.forceContiguousSeq(ns, serverAck);
+                        }
+                    }
                     // 持久化 cursor + ack_events（与 Python 对齐）
                     this._saveSeqTrackerState();
                     const contig = this._seqTracker.getContiguousSeq(ns);
-                    if (contig > 0) {
+                    if (contig > 0 && (events.length > 0 || serverAck > 0)) {
                         this._transport.call('group.ack_events', {
                             group_id: groupId,
                             event_seq: contig,
                             device_id: this._deviceId,
+                            slot_id: this._slotId,
                         }).catch((e) => { console.warn('群事件 auto-ack 失败: group=' + groupId, e); });
                     }
                     for (const evt of events) {
@@ -989,10 +1052,6 @@ export class AUNClient {
             return;
         const ns = `p2p:${this._aid}`;
         const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        // 新设备（seq=0）没有历史 prekey，拉旧消息也解不了
-        if (afterSeq === 0) {
-            return;
-        }
         // 去重：同一 (type:after_seq) 在飞行中只补一次
         // S1: 使用 try/finally 保证无论成功失败都清理 dedupKey
         const dedupKey = `p2p:${afterSeq}`;
@@ -1016,7 +1075,12 @@ export class AUNClient {
                             const s = msg.seq;
                             if (pushed && s !== undefined && s !== null && pushed.has(s))
                                 continue;
-                            await this._dispatcher.publish('message.received', msg);
+                            if (s !== undefined && s !== null) {
+                                await this._publishOrderedMessage('message.received', ns, s, msg);
+                            }
+                            else {
+                                await this._publishAppEvent('message.received', msg);
+                            }
                         }
                     }
                     this._prunePushedSeqs(ns);
@@ -1045,6 +1109,119 @@ export class AUNClient {
         if (pushed.size === 0)
             this._pushedSeqs.delete(ns);
     }
+    _markPublishedSeq(ns, seq) {
+        let pushed = this._pushedSeqs.get(ns);
+        if (!pushed) {
+            pushed = new Set();
+            this._pushedSeqs.set(ns, pushed);
+        }
+        pushed.add(seq);
+        if (pushed.size > PUSHED_SEQS_LIMIT) {
+            const keep = [...pushed].sort((a, b) => a - b).slice(-PUSHED_SEQS_LIMIT);
+            this._pushedSeqs.set(ns, new Set(keep));
+        }
+    }
+    _enqueueOrderedMessage(ns, event, seq, payload) {
+        let queue = this._pendingOrderedMsgs.get(ns);
+        if (!queue) {
+            queue = new Map();
+            this._pendingOrderedMsgs.set(ns, queue);
+        }
+        queue.set(seq, { event, payload });
+        if (queue.size > PENDING_ORDERED_LIMIT) {
+            const drop = [...queue.keys()].sort((a, b) => a - b).slice(0, queue.size - PENDING_ORDERED_LIMIT);
+            for (const oldSeq of drop)
+                queue.delete(oldSeq);
+        }
+    }
+    _isInstanceScopedMessageEvent(event) {
+        return event === 'message.received'
+            || event === 'message.undecryptable'
+            || event === 'group.message_created'
+            || event === 'group.message_undecryptable';
+    }
+    _attachCurrentInstanceContext(payload) {
+        if (!isJsonObject(payload))
+            return payload;
+        const result = { ...payload };
+        if (this._deviceId && !String(result.device_id ?? '').trim()) {
+            result.device_id = this._deviceId;
+        }
+        if (this._slotId && !String(result.slot_id ?? '').trim()) {
+            result.slot_id = this._slotId;
+        }
+        return result;
+    }
+    _normalizePublishedMessagePayload(event, payload) {
+        if (!this._isInstanceScopedMessageEvent(event))
+            return payload;
+        return this._attachCurrentInstanceContext(payload);
+    }
+    async _publishAppEvent(event, payload) {
+        await this._dispatcher.publish(event, this._normalizePublishedMessagePayload(event, payload));
+    }
+    _messageTargetsCurrentInstance(message) {
+        if (!isJsonObject(message))
+            return true;
+        const targetDeviceId = String(message.device_id ?? '').trim();
+        if (targetDeviceId && this._deviceId && targetDeviceId !== this._deviceId) {
+            return false;
+        }
+        const targetSlotId = String(message.slot_id ?? '').trim();
+        if (targetSlotId && this._slotId && targetSlotId !== this._slotId) {
+            return false;
+        }
+        return true;
+    }
+    async _drainOrderedMessages(ns, beforeSeq) {
+        const queue = this._pendingOrderedMsgs.get(ns);
+        if (!queue || queue.size === 0)
+            return;
+        const contig = this._seqTracker.getContiguousSeq(ns);
+        const ready = [...queue.keys()]
+            .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
+            .sort((a, b) => a - b);
+        for (const seq of ready) {
+            const item = queue.get(seq);
+            queue.delete(seq);
+            if (!item || this._pushedSeqs.get(ns)?.has(seq))
+                continue;
+            await this._publishAppEvent(item.event, item.payload);
+            this._markPublishedSeq(ns, seq);
+        }
+        if (queue.size === 0)
+            this._pendingOrderedMsgs.delete(ns);
+    }
+    async _publishOrderedMessage(event, ns, seq, payload) {
+        const seqNum = Number(seq);
+        if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
+            await this._publishAppEvent(event, payload);
+            return true;
+        }
+        if (this._pushedSeqs.get(ns)?.has(seqNum)) {
+            const queue = this._pendingOrderedMsgs.get(ns);
+            queue?.delete(seqNum);
+            if (queue && queue.size === 0)
+                this._pendingOrderedMsgs.delete(ns);
+            return false;
+        }
+        const contig = this._seqTracker.getContiguousSeq(ns);
+        if (seqNum > contig) {
+            this._enqueueOrderedMessage(ns, event, seqNum, payload);
+            return false;
+        }
+        await this._drainOrderedMessages(ns, seqNum);
+        if (this._pushedSeqs.get(ns)?.has(seqNum))
+            return false;
+        const queue = this._pendingOrderedMsgs.get(ns);
+        queue?.delete(seqNum);
+        if (queue && queue.size === 0)
+            this._pendingOrderedMsgs.delete(ns);
+        await this._publishAppEvent(event, payload);
+        this._markPublishedSeq(ns, seqNum);
+        await this._drainOrderedMessages(ns);
+        return true;
+    }
     /**
      * 上线/重连后一次性同步所有已加入群：
      * 1. 有 epoch key 的群 → 补消息 + 补事件
@@ -1313,6 +1490,8 @@ export class AUNClient {
         // 4. 清理推送 seq 去重缓存
         this._pushedSeqs.delete(`group:${groupId}`);
         this._pushedSeqs.delete(`group_event:${groupId}`);
+        this._pendingOrderedMsgs.delete(`group:${groupId}`);
+        this._pendingDecryptMsgs.delete(`group:${groupId}`);
         console.info(`[aun_core] 已清理解散群组 ${groupId} 的本地状态`);
     }
     async _verifyEventSignature(_event, cs) {
@@ -1346,11 +1525,19 @@ export class AUNClient {
             const ok = await ecdsaVerifyDer(pubKey, sigBytes, signData);
             if (!ok) {
                 console.warn('[aun_core] 群事件验签失败 aid=%s method=%s', sigAid, method);
+                // P1-16: 签名失败统一发布事件
+                this._dispatcher.publish('signature.verification_failed', {
+                    aid: sigAid, method, error: 'ECDSA verification failed',
+                });
             }
             return ok;
         }
         catch (exc) {
             console.warn('[aun_core] 群事件验签异常:', exc);
+            // P1-16: 签名失败统一发布事件
+            this._dispatcher.publish('signature.verification_failed', {
+                aid: sigAid, method, error: String(exc),
+            });
             return false;
         }
     }
@@ -1666,49 +1853,114 @@ export class AUNClient {
     }
     /** 自动加密并发送群组消息 */
     async _sendGroupEncrypted(params) {
-        const groupId = String(params.group_id ?? '');
+        return this._callGroupEncryptedRpc('group.send', params, {
+            idField: 'message_id',
+            idPrefix: 'gm',
+        });
+    }
+    async _putGroupThoughtEncrypted(params) {
+        return this._callGroupEncryptedRpc('group.thought.put', params, {
+            idField: 'thought_id',
+            idPrefix: 'gt',
+            extraFields: ['reply_to'],
+        });
+    }
+    async _putMessageThoughtEncrypted(params) {
+        const toAid = String(params.to ?? '').trim();
+        this._validateMessageRecipient(toAid);
         const payload = isJsonObject(params.payload) ? params.payload : null;
-        if (!groupId) {
-            throw new ValidationError('group.send requires group_id');
+        if (!toAid) {
+            throw new ValidationError('message.thought.put requires to');
         }
         if (payload === null) {
-            throw new ValidationError('group.send payload must be an object when encrypt=true');
+            throw new ValidationError('message.thought.put payload must be an object when encrypt=true');
         }
-        // Lazy group sync：首次发送群消息前自动拉取历史，避免重连后 seq 空洞
-        if (!this._groupSynced.has(groupId)) {
-            await this._lazySyncGroup(groupId);
-        }
-        await this._ensureGroupEpochReady(groupId, false);
-        await this._waitForGroupMembershipEpochFloor(groupId, 2000);
+        const thoughtId = String(params.thought_id ?? '') || `mt-${_uuidV4()}`;
+        const timestamp = Number(params.timestamp ?? Date.now());
+        const prekey = await this._fetchPeerPrekey(toAid);
+        const peerCertFingerprint = typeof prekey?.cert_fingerprint === 'string' ? prekey.cert_fingerprint : undefined;
+        const peerCertPem = await this._fetchPeerCert(toAid, peerCertFingerprint);
+        const [envelope, encryptResult] = await this._encryptCopyPayload({
+            logicalToAid: toAid,
+            payload,
+            peerCertPem,
+            prekey,
+            messageId: thoughtId,
+            timestamp,
+        });
+        await this._ensureEncryptResult(toAid, encryptResult);
+        const sendParams = {
+            to: toAid,
+            payload: envelope,
+            type: 'e2ee.encrypted',
+            encrypted: true,
+            thought_id: thoughtId,
+            timestamp,
+            reply_to: params.reply_to,
+        };
+        await this._signClientOperation('message.thought.put', sendParams);
+        return this._transport.call('message.thought.put', sendParams);
+    }
+    async _callGroupEncryptedRpc(method, params, options) {
+        let prepared = await this._prepareGroupEncryptedRpcParams(method, params, options);
         for (let attempt = 0; attempt < 2; attempt += 1) {
-            const epochResult = await this._committedGroupEpochState(groupId);
-            const committedEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
-            const envelope = committedEpoch > 0
-                ? await this._groupE2ee.encryptWithEpoch(groupId, await this._ensureCommittedGroupSecretForSend(groupId, committedEpoch, epochResult), payload)
-                : await this._groupE2ee.encrypt(groupId, payload);
-            const sendParams = {
-                group_id: groupId,
-                payload: envelope,
-                type: 'e2ee.group_encrypted',
-                encrypted: true,
-            };
-            if (this._deviceId && sendParams.device_id === undefined) {
-                sendParams.device_id = this._deviceId;
-            }
-            await this._signClientOperation('group.send', sendParams);
             try {
-                return await this._transport.call('group.send', sendParams);
+                return await this._transport.call(method, prepared.sendParams);
             }
             catch (exc) {
                 if (attempt === 0 && this._isRecoverableGroupEpochError(exc)) {
-                    console.warn(`[aun_core] 群 ${groupId} 发送时 epoch 已过旧，恢复密钥后重加密重发一次: ${formatCaughtError(exc)}`);
-                    await this._ensureGroupEpochReady(groupId, true);
+                    console.warn(`[aun_core] 群 ${prepared.groupId} 调用 ${method} 时 epoch 已过旧，恢复密钥后重加密重试一次: ${formatCaughtError(exc)}`);
+                    prepared = await this._prepareGroupEncryptedRpcParams(method, params, options, true);
                     continue;
                 }
                 throw exc;
             }
         }
-        throw new StateError(`group ${groupId} send failed after epoch recovery retry`);
+        throw new StateError(`${method} failed after epoch recovery retry: group=${prepared.groupId}`);
+    }
+    async _prepareGroupEncryptedRpcParams(method, params, options, strictEpochReady = false) {
+        const groupId = String(params.group_id ?? '');
+        const payload = isJsonObject(params.payload) ? params.payload : null;
+        if (!groupId) {
+            throw new ValidationError(`${method} requires group_id`);
+        }
+        if (payload === null) {
+            throw new ValidationError(`${method} payload must be an object when encrypt=true`);
+        }
+        if (!this._groupSynced.has(groupId)) {
+            await this._lazySyncGroup(groupId);
+        }
+        await this._ensureGroupEpochReady(groupId, strictEpochReady);
+        await this._waitForGroupMembershipEpochFloor(groupId, 2000);
+        const epochResult = await this._committedGroupEpochState(groupId);
+        const committedEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
+        const envelope = committedEpoch > 0
+            ? await this._groupE2ee.encryptWithEpoch(groupId, await this._ensureCommittedGroupSecretForSend(groupId, committedEpoch, epochResult), payload)
+            : await this._groupE2ee.encrypt(groupId, payload);
+        const operationId = String(params[options.idField] ?? '').trim()
+            || `${options.idPrefix}-${crypto.randomUUID()}`;
+        const timestamp = Number(params.timestamp ?? Date.now());
+        const sendParams = {
+            group_id: groupId,
+            payload: envelope,
+            type: 'e2ee.group_encrypted',
+            encrypted: true,
+            [options.idField]: operationId,
+            timestamp,
+        };
+        if (this._deviceId && sendParams.device_id === undefined) {
+            sendParams.device_id = this._deviceId;
+        }
+        if (sendParams.slot_id === undefined) {
+            sendParams.slot_id = this._slotId;
+        }
+        for (const field of options.extraFields ?? []) {
+            if (params[field] !== undefined) {
+                sendParams[field] = params[field];
+            }
+        }
+        await this._signClientOperation(method, sendParams);
+        return { sendParams, groupId };
     }
     /**
      * 首次发送群消息前懒拉取历史消息，同步 seqTracker 避免空洞。
@@ -2030,7 +2282,7 @@ export class AUNClient {
         const ns = `group:${groupId}`;
         const queue = this._pendingDecryptMsgs.get(ns) ?? [];
         queue.push(msg);
-        this._pendingDecryptMsgs.set(ns, queue.slice(-200));
+        this._pendingDecryptMsgs.set(ns, queue.slice(-PENDING_DECRYPT_LIMIT));
     }
     async _retryPendingDecryptMsgs(groupId) {
         const ns = `group:${groupId}`;
@@ -2047,14 +2299,20 @@ export class AUNClient {
                     stillPending.push(msg);
                     continue;
                 }
-                await this._dispatcher.publish('group.message_created', decrypted);
+                const seq = msg.seq;
+                if (seq !== undefined && seq !== null) {
+                    await this._publishOrderedMessage('group.message_created', ns, seq, decrypted);
+                }
+                else {
+                    await this._publishAppEvent('group.message_created', decrypted);
+                }
             }
             catch {
                 stillPending.push(msg);
             }
         }
         const queuedDuringRetry = this._pendingDecryptMsgs.get(ns) ?? [];
-        const mergedPending = [...stillPending, ...queuedDuringRetry].slice(-200);
+        const mergedPending = [...stillPending, ...queuedDuringRetry].slice(-PENDING_DECRYPT_LIMIT);
         if (mergedPending.length)
             this._pendingDecryptMsgs.set(ns, mergedPending);
         else
@@ -2144,7 +2402,7 @@ export class AUNClient {
     async _decryptGroupMessage(message, opts) {
         const payload = isJsonObject(message.payload) ? message.payload : null;
         if (payload === null || payload.type !== 'e2ee.group_encrypted') {
-            return message;
+            return this._attachGroupDispatchModeToPayload(message);
         }
         // 确保发送方证书已缓存（签名验证需要）
         const senderAid = String(message.from ?? message.sender_aid ?? '');
@@ -2158,7 +2416,7 @@ export class AUNClient {
         // 先尝试直接解密
         const result = await this._groupE2ee.decrypt(message, opts);
         if (result !== null && isJsonObject(result.e2ee)) {
-            return result;
+            return this._attachGroupDispatchModeToPayload(result);
         }
         // replay guard 命中：decrypt 返回了原消息（非 null）但无 e2ee 字段
         // 不是解密失败，不应触发 recover
@@ -2174,7 +2432,7 @@ export class AUNClient {
                 if (await this._recoverGroupEpochKey(groupId, epoch, sender, 5000)) {
                     const retry = await this._groupE2ee.decrypt(message, opts);
                     if (retry !== null && retry.e2ee)
-                        return retry;
+                        return this._attachGroupDispatchModeToPayload(retry);
                 }
             }
             catch (exc) {
@@ -2183,6 +2441,21 @@ export class AUNClient {
         }
         return message;
     }
+    _attachGroupDispatchModeToPayload(message) {
+        const payload = message.payload;
+        if (!isJsonObject(payload))
+            return message;
+        const rawMode = String(message.dispatch_mode ?? 'broadcast').trim().toLowerCase();
+        const mode = rawMode === 'mention' || rawMode === 'broadcast' ? rawMode : 'broadcast';
+        return {
+            ...message,
+            dispatch_mode: mode,
+            payload: {
+                ...payload,
+                dispatch_mode: mode,
+            },
+        };
+    }
     /** 批量解密群组消息（用于 group.pull）。跳过防重放检查。 */
     async _decryptGroupMessages(messages) {
         const result = [];
@@ -2194,10 +2467,104 @@ export class AUNClient {
                 this._enqueuePendingDecrypt(groupId, msg);
                 continue; // R3: 解密失败不入 result，不 publish 密文给应用层
             }
+            if (payload?.type !== 'e2ee.group_encrypted') {
+                result.push(this._attachGroupDispatchModeToPayload(decrypted));
+                continue;
+            }
             result.push(decrypted);
         }
         return result;
     }
+    async _decryptGroupThoughts(result) {
+        if (!result.found) {
+            return { ...result, thoughts: [] };
+        }
+        const items = (Array.isArray(result.thoughts) ? result.thoughts : []).filter(isJsonObject);
+        if (!items.length) {
+            return { ...result, thoughts: [] };
+        }
+        const groupId = String(result.group_id ?? '');
+        const senderAid = String(result.sender_aid ?? '');
+        const thoughts = [];
+        for (const item of items) {
+            const payload = isJsonObject(item.payload) ? item.payload : null;
+            const thoughtId = String(item.thought_id ?? item.message_id ?? '');
+            const message = {
+                group_id: groupId,
+                sender_aid: senderAid,
+                from: senderAid,
+                message_id: thoughtId,
+                payload: payload ?? {},
+                created_at: Number(item.created_at ?? 0),
+            };
+            const decrypted = await this._decryptGroupMessage(message, { skipReplay: true });
+            if (payload?.type === 'e2ee.group_encrypted' && groupId && !decrypted.e2ee) {
+                this._enqueuePendingDecrypt(groupId, message);
+                continue;
+            }
+            thoughts.push({
+                thought_id: thoughtId,
+                message_id: thoughtId,
+                reply_to: item.reply_to,
+                payload: decrypted.payload,
+                created_at: item.created_at,
+                e2ee: decrypted.e2ee,
+            });
+        }
+        return { ...result, thoughts };
+    }
+    async _decryptMessageThoughts(result) {
+        if (!result.found) {
+            return { ...result, thoughts: [] };
+        }
+        const items = (Array.isArray(result.thoughts) ? result.thoughts : []).filter(isJsonObject);
+        if (!items.length) {
+            return { ...result, thoughts: [] };
+        }
+        const senderAid = String(result.sender_aid ?? '');
+        const peerAid = String(result.peer_aid ?? '');
+        const thoughts = [];
+        for (const item of items) {
+            const payload = isJsonObject(item.payload) ? item.payload : null;
+            const thoughtId = String(item.thought_id ?? item.message_id ?? '');
+            const fromAid = String(item.from ?? senderAid);
+            const toAid = String(item.to ?? peerAid);
+            const message = {
+                from: fromAid,
+                to: toAid,
+                message_id: thoughtId,
+                payload: payload ?? {},
+                encrypted: item.encrypted !== false,
+                timestamp: Number(item.created_at ?? 0),
+            };
+            let decrypted = message;
+            if (payload?.type === 'e2ee.encrypted') {
+                const senderCertFingerprint = String(payload.sender_cert_fingerprint ?? payload.aad?.sender_cert_fingerprint ?? '').trim().toLowerCase();
+                if (fromAid) {
+                    const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
+                    if (!certReady) {
+                        console.warn('[aun_core] 无法获取发送方证书，跳过 message.thought.get 解密:', fromAid);
+                        continue;
+                    }
+                }
+                decrypted = await this._e2ee.decryptMessage(message, { skipReplay: true });
+                if (decrypted === null || (isJsonObject(decrypted.payload) && decrypted.payload.type === 'e2ee.encrypted')) {
+                    continue;
+                }
+            }
+            thoughts.push({
+                thought_id: thoughtId,
+                message_id: thoughtId,
+                reply_to: item.reply_to,
+                from: fromAid,
+                to: toAid,
+                payload: decrypted.payload,
+                created_at: item.created_at,
+                e2ee: decrypted.e2ee,
+            });
+        }
+        return { ...result, thoughts };
+    }
     /**
      * 尝试处理 P2P 传输的群组密钥消息。
      *
@@ -3292,34 +3659,45 @@ export class AUNClient {
         // 避免 reader 把积压 push 交给空 tracker 的 handler，触发 S2 历史 gap 误补拉。
         this._refreshSeqTrackerContext();
         await this._restoreSeqTrackerState();
-        const challenge = await this._transport.connect(gatewayUrl);
-        this._state = 'authenticating';
-        if (allowReauth) {
-            const authContext = await this._auth.connectSession(this._transport, challenge, gatewayUrl, {
-                accessToken: params.access_token,
-                deviceId: this._deviceId,
-                slotId: this._slotId,
-                deliveryMode: this._connectDeliveryMode,
-            });
-            if (isJsonObject(authContext)) {
-                const auth = authContext;
-                const identity = auth.identity;
-                if (identity && isJsonObject(identity)) {
-                    this._identity = identity;
-                    this._aid = String(identity.aid ?? this._aid ?? '');
-                    if (this._sessionParams) {
-                        this._sessionParams.access_token = String(auth.token ?? params.access_token ?? '');
+        try {
+            const challenge = await this._transport.connect(gatewayUrl);
+            this._state = 'authenticating';
+            if (allowReauth) {
+                const authContext = await this._auth.connectSession(this._transport, challenge, gatewayUrl, {
+                    accessToken: params.access_token,
+                    deviceId: this._deviceId,
+                    slotId: this._slotId,
+                    deliveryMode: this._connectDeliveryMode,
+                });
+                if (isJsonObject(authContext)) {
+                    const auth = authContext;
+                    const identity = auth.identity;
+                    if (identity && isJsonObject(identity)) {
+                        this._identity = identity;
+                        this._aid = String(identity.aid ?? this._aid ?? '');
+                        if (this._sessionParams) {
+                            this._sessionParams.access_token = String(auth.token ?? params.access_token ?? '');
+                        }
                     }
                 }
             }
+            else {
+                await this._auth.initializeWithToken(this._transport, challenge, String(params.access_token), {
+                    deviceId: this._deviceId,
+                    slotId: this._slotId,
+                    deliveryMode: this._connectDeliveryMode,
+                });
+                await this._syncIdentityAfterConnect(String(params.access_token));
+            }
         }
-        else {
-            await this._auth.initializeWithToken(this._transport, challenge, String(params.access_token), {
-                deviceId: this._deviceId,
-                slotId: this._slotId,
-                deliveryMode: this._connectDeliveryMode,
-            });
-            await this._syncIdentityAfterConnect(String(params.access_token));
+        catch (err) {
+            // P1-19: 首连失败时重置状态，避免半连接残留
+            this._state = 'disconnected';
+            try {
+                await this._transport.close();
+            }
+            catch { /* 忽略关闭错误 */ }
+            throw err;
         }
         this._state = 'connected';
         await this._dispatcher.publish('connection.state', {
@@ -3666,6 +4044,26 @@ export class AUNClient {
                 throw new ValidationError('group.send does not accept delivery_mode; group messages are always fanout');
             }
         }
+        if (method === 'group.thought.put' || method === 'group.thought.get'
+            || method === 'message.thought.put' || method === 'message.thought.get') {
+            const replyTo = isJsonObject(params.reply_to) ? params.reply_to : null;
+            const replyMsgId = String(replyTo?.message_id ?? '').trim();
+            if (!replyMsgId) {
+                throw new ValidationError(`${method} requires reply_to.message_id`);
+            }
+        }
+        if (method === 'group.thought.get' && !String(params.sender_aid ?? '').trim()) {
+            throw new ValidationError('group.thought.get requires sender_aid');
+        }
+        if (method === 'message.thought.put') {
+            this._validateMessageRecipient(params.to);
+            if (!String(params.to ?? '').trim()) {
+                throw new ValidationError('message.thought.put requires to');
+            }
+        }
+        if (method === 'message.thought.get' && !String(params.sender_aid ?? '').trim()) {
+            throw new ValidationError('message.thought.get requires sender_aid');
+        }
     }
     _currentMessageDeliveryMode() {
         return { ...this._connectDeliveryMode };
@@ -3959,6 +4357,8 @@ export class AUNClient {
         this._seqTrackerContext = null;
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
+        this._pendingOrderedMsgs.clear();
+        this._pendingDecryptMsgs.clear();
         this._groupSynced.clear();
         this._p2pSynced = false;
     }
@@ -3969,6 +4369,8 @@ export class AUNClient {
         this._seqTracker = new SeqTracker();
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
+        this._pendingOrderedMsgs.clear();
+        this._pendingDecryptMsgs.clear();
         this._groupSynced.clear();
         this._p2pSynced = false;
         this._seqTrackerContext = nextContext;