@agentunion/fastaun 0.5.33 → 0.5.35

package/dist/client/delivery.js

@@ -14,6 +14,11 @@ const GROUP_RECALL_SEEN_LIMIT = 10_000;
 const VOLATILE_SEEN_LIMIT = 10_000;
 const SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS = 200;
 const BACKGROUND_PULL_RETRY_DELAY_MS = 250;
+function isOversizedPullError(error) {
+    const failure = error;
+    return [failure?.data?.code, failure?.data?.reason, failure?.stringCode].includes('OVERSIZED_MESSAGE')
+        || String(failure?.message ?? '').includes('OVERSIZED_MESSAGE');
+}
 function isTerminalGroupPullError(error) {
     if (!error || typeof error !== 'object')
         return false;
@@ -99,9 +104,73 @@ function deduplicatePlainForwardPageMessages(value, afterSeq) {
 }
 export class MessageDeliveryEngine {
     runtime;
+    forwardAckJobs = new Map();
+    forwardAckTasks = new Set();
+    scheduleForwardAck(ns, seq, send) {
+        const client = this.runtime.client;
+        if (client._closing || seq <= 0)
+            return;
+        const scope = () => [client._aid, client._deviceId, client._slotId, this.captureInlineAckGeneration(),
+            client._v2RuntimeGeneration, client._transport, client._transport?._connectionGeneration,
+            client._transport?._workerGeneration, this.captureSeqNamespaceGeneration(ns)];
+        const current = scope();
+        const previous = this.forwardAckJobs.get(ns);
+        if (previous && previous.scope.every((value, i) => value === current[i])) {
+            if (seq > previous.seq) {
+                previous.seq = seq;
+                previous.send = send;
+            }
+            return;
+        }
+        const job = { seq, scope: current, send };
+        this.forwardAckJobs.set(ns, job);
+        const isCurrent = () => this.forwardAckJobs.get(ns) === job && job.scope.every((value, i) => value === scope()[i]);
+        const task = (async () => {
+            let failures = 0;
+            while (isCurrent()) {
+                const pending = job.seq;
+                try {
+                    await job.send(pending);
+                    failures = 0;
+                    if (job.seq <= pending) {
+                        if (this.forwardAckJobs.get(ns) === job)
+                            this.forwardAckJobs.delete(ns);
+                        return;
+                    }
+                }
+                catch {
+                    if (!isCurrent() || client._closing || client.state !== ConnectionState.READY)
+                        return;
+                    if (job.seq <= pending)
+                        await new Promise(resolve => setTimeout(resolve, Math.min(100 * 2 ** Math.min(failures++, 5), 3000)));
+                }
+            }
+        })().finally(() => {
+            if (this.forwardAckJobs.get(ns) === job)
+                this.forwardAckJobs.delete(ns);
+            this.forwardAckTasks.delete(task);
+        });
+        this.forwardAckTasks.add(task);
+    }
+    drainForwardAcks() {
+        if (!this.forwardAckTasks.size)
+            return;
+        return this.waitForwardAcks();
+    }
+    async waitForwardAcks() {
+        let timer;
+        try {
+            await Promise.race([Promise.allSettled([...this.forwardAckTasks]), new Promise(resolve => { timer = setTimeout(resolve, 1000); })]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     realtimeTailHeads = null;
     realtimeSyncing = null;
     pendingGroupPullUpper = null;
+    pendingV2GroupPulls = new Set();
     onlineUnreadHintTargets = null;
     onlineUnreadHintTasks = null;
     backgroundPullNeeds = new Map();
@@ -135,6 +204,9 @@ export class MessageDeliveryEngine {
     seqTrackerNamespaceGenerations = new Map();
     peerRecoveryTasks = new Map();
     peerRecoveryNeeds = new Map();
+    peerVolatileNeeds = new Set();
+    peerVolatileTask = null;
+    oversizedPulls = new Set();
     peerForwardNeeds = new Map();
     peerPushVersions = new Map();
     peerCatalogVersion = null;
@@ -163,6 +235,7 @@ export class MessageDeliveryEngine {
         this.automaticPullFailures.clear();
         this.terminalGroupPulls.clear();
         this.groupPullVersions.clear();
+        this.oversizedPulls.clear();
     }
     groupPullNamespace(namespace) {
         let groupId = namespace.startsWith('group_event:') ? namespace.slice('group_event:'.length)
@@ -267,6 +340,17 @@ export class MessageDeliveryEngine {
             catch (error) {
                 if (!groupCurrent())
                     throw new Error('pull invalidated');
+                if (!signal.aborted && generation === this.captureInlineAckGeneration() && isOversizedPullError(error)) {
+                    this.oversizedPulls.add(namespace);
+                    this.automaticPullFailures.delete(namespace);
+                    this.backgroundPullNeeds.delete(namespace);
+                    const peer = this.peerRecoveryNeeds.get(this.peerSender(namespace));
+                    if (peer)
+                        peer.paused = true;
+                    if (this.groupPullNamespace(namespace))
+                        this.stopAutomaticGroupPull(namespace, error);
+                    throw error;
+                }
                 if (!signal.aborted && generation === this.captureInlineAckGeneration()
                     && this.groupPullNamespace(namespace) && isTerminalGroupPullError(error)) {
                     this.stopAutomaticGroupPull(namespace, error);
@@ -471,6 +555,8 @@ export class MessageDeliveryEngine {
             this.peerPullConfirmedThrough.clear();
             this.peerServerConfirmedAcks.clear();
             this.peerRecoveryTasks.clear();
+            this.peerVolatileNeeds.clear();
+            this.peerVolatileTask = null;
             this.settledDeliveries.clear();
             this.deliveryInflight.clear();
             this.peerCatalogTask = null;
@@ -791,6 +877,8 @@ export class MessageDeliveryEngine {
     }
     refreshPendingPeers() {
         this.ensurePeerContext();
+        if (this.oversizedPulls.has('message.peers'))
+            return;
         this.peerCatalogVersion = {};
         if (!this.hasP2pApplicationSubscription())
             return;
@@ -818,15 +906,57 @@ export class MessageDeliveryEngine {
             }
         })();
         this.peerCatalogTask = task.then(() => ({}), () => ({}));
-        client._safeAsync(task.catch(() => {
+        client._safeAsync(task.catch((error) => {
             if (generation !== this.captureInlineAckGeneration())
                 return;
+            if (isOversizedPullError(error))
+                return;
             const timer = setTimeout(() => { if (generation === this.captureInlineAckGeneration())
                 this.refreshPendingPeers(); }, BACKGROUND_PULL_RETRY_DELAY_MS);
             timer.unref?.();
         }).finally(() => { if (generation === this.captureInlineAckGeneration())
             this.peerCatalogTask = null; }));
     }
+    schedulePeerVolatileRecovery(sender) {
+        const client = this.runtime.client;
+        const namespace = `${this.peerNamespace(sender)}|volatile`;
+        if (this.oversizedPulls.has(namespace))
+            return;
+        this.peerVolatileNeeds.add(sender);
+        if (this.peerVolatileTask)
+            return;
+        const generation = this.captureInlineAckGeneration(), context = this.ensurePeerContext();
+        const current = () => generation === this.captureInlineAckGeneration() && context === this.ensurePeerContext();
+        const task = (async () => {
+            while (current() && this.peerVolatileNeeds.size && this.hasP2pApplicationSubscription()
+                && client._sessionOptions?.background_sync !== false && !client._closing) {
+                const peer = this.peerVolatileNeeds.values().next().value;
+                this.peerVolatileNeeds.delete(peer);
+                try {
+                    const result = await client._v2E2EE.pullPeerV2Volatile(peer, { background: true, retainMessages: false, maxPages: 1 });
+                    if (!current())
+                        return;
+                    if (!result.complete)
+                        this.peerVolatileNeeds.add(peer);
+                }
+                catch (error) {
+                    if (!current())
+                        return;
+                    if (isOversizedPullError(error)) {
+                        this.oversizedPulls.add(`${this.peerNamespace(peer)}|volatile`);
+                        client._dispatcher.enqueue('sync.error', { namespace: `${this.peerNamespace(peer)}|volatile`, method: 'message.v2.pull', code: 'OVERSIZED_MESSAGE', error: String(error) });
+                    }
+                    else
+                        client._safeAsync(Promise.reject(error));
+                }
+            }
+        })();
+        this.peerVolatileTask = task;
+        client._safeAsync(task.finally(() => {
+            if (current() && this.peerVolatileTask === task)
+                this.peerVolatileTask = null;
+        }));
+    }
     schedulePeerRecovery(sender, head = 0, volatile = false) {
         const client = this.runtime.client;
         if (!sender || client._closing)
@@ -855,6 +985,11 @@ export class MessageDeliveryEngine {
             this.peerForwardNeeds.set(namespace, {});
             return;
         }
+        if (volatile && client._syncChannelCoordinator?.needsSplit?.()
+            && (this.peerRecoveryTasks.has(sender) || this.oversizedPulls.has(namespace)))
+            this.schedulePeerVolatileRecovery(sender);
+        if (this.oversizedPulls.has(namespace))
+            return;
         const need = this.peerRecoveryNeeds.get(sender) ?? { head: 0, volatile: false, pending: false };
         need.paused = false;
         need.head = Math.max(need.head, head);
@@ -953,9 +1088,11 @@ export class MessageDeliveryEngine {
             }
         })();
         this.peerRecoveryTasks.set(sender, task);
-        client._safeAsync(task.catch(() => {
+        client._safeAsync(task.catch((error) => {
             if (generation !== this.captureInlineAckGeneration())
                 return;
+            if (isOversizedPullError(error) || need.paused)
+                return;
             const timer = setTimeout(() => {
                 if (generation === this.captureInlineAckGeneration() && this.peerRecoveryNeeds.get(sender) === need
                     && !need.paused && !this.peerRecoveryTasks.has(sender))
@@ -1033,7 +1170,7 @@ export class MessageDeliveryEngine {
             this.onGroupV2AckSucceeded(groupId, actualAckSeq, generation);
         }
     }
-    async commitPlainForwardPage(ns, afterSeq, method, result, groupId = '') {
+    async commitPlainForwardPage(ns, afterSeq, method, result, groupId = '', background = false) {
         if (!isJsonObject(result)) {
             throw new Error(`${method} response must be an object`);
         }
@@ -1177,7 +1314,10 @@ export class MessageDeliveryEngine {
                 throw new Error(`${ackMethod} cannot confirm pending Forward watermark ${pendingAckSeq}`);
             }
             this.ensurePullOperationCurrent(ns);
-            await this.confirmPlainForwardAck(ns, ackMethod, pendingAckSeq, groupId);
+            if (background)
+                this.scheduleForwardAck(ns, pendingAckSeq, seq => this.confirmPlainForwardAck(ns, ackMethod, seq, groupId));
+            else
+                await this.confirmPlainForwardAck(ns, ackMethod, pendingAckSeq, groupId);
         }
         this.syncProgress(ns, {
             rawCount: messages.length,
@@ -1385,6 +1525,7 @@ export class MessageDeliveryEngine {
         this.pendingGroupInlineAckNamespaces = null;
         this.realtimeSyncing = null;
         this.pendingGroupPullUpper = null;
+        this.pendingV2GroupPulls.clear();
         this.onlineUnreadHintTargets = null;
         this.onlineUnreadHintTasks = null;
         this.realtimeTailHeads = null;
@@ -1399,6 +1540,8 @@ export class MessageDeliveryEngine {
         this.peerPullConfirmedThrough.clear();
         this.peerServerConfirmedAcks.clear();
         this.peerRecoveryTasks.clear();
+        this.peerVolatileNeeds.clear();
+        this.peerVolatileTask = null;
     }
     deliveryChangedNamespace(event, payload) {
         if (event === 'group.message_created' && isJsonObject(payload)) {
@@ -1669,8 +1812,31 @@ export class MessageDeliveryEngine {
     pendingPullUpper(ns) {
         return this.pendingGroupPullUpper?.get(ns) ?? 0;
     }
+    pendingHistoryNamespaces() {
+        const namespaces = new Set(), client = this.runtime.client, now = Date.now();
+        for (const [sender, need] of this.peerRecoveryNeeds) {
+            const ns = this.peerNamespace(sender);
+            if (need.pending && !need.paused && !this.peerRecoveryTasks.has(sender) && !this.oversizedPulls.has(ns)
+                && (this.automaticPullFailures.get(ns)?.retryAt ?? 0) <= now)
+                namespaces.add(ns);
+        }
+        for (const [ns, need] of this.backgroundPullNeeds) {
+            if (need.messageClassRequest || need.retryAt > now || !(need.probe || need.hasMore)
+                || this.automaticGroupPullStopped(ns) || this.oversizedPulls.has(ns) || this.backgroundPullTasks.has(ns)
+                || this.realtimeSyncing?.has(ns) || this.onlineUnreadHintTasks?.has(ns))
+                continue;
+            const eventScope = ns.startsWith('group_event:');
+            if ((!eventScope && client._rpcPipeline?.hasPullActivity?.(ns, false))
+                || (eventScope && ['pulling', 'processing', 'pulled'].includes(client._rpcPipeline?.getPullLifecycle?.(ns))))
+                continue;
+            if (ns.startsWith('group:') || eventScope || ns === `p2p:${client._aid}`)
+                namespaces.add(ns);
+        }
+        return [...namespaces];
+    }
     hasAnyPendingPull() {
         return this.peerCatalogDirty || [...this.peerRecoveryNeeds.values()].some((need) => !need.paused) || this.peerRecoveryTasks.size > 0 || Boolean(this.peerCatalogTask)
+            || Boolean(this.peerVolatileTask) || this.peerVolatileNeeds.size > 0
             || [...(this.pendingGroupPullUpper?.values() ?? [])].some((seq) => seq > 0)
             || [...this.backgroundPullNeeds.values()].some((need) => need.retryAt !== Infinity)
             || Boolean(this.onlineUnreadHintTasks?.size)
@@ -1696,7 +1862,7 @@ export class MessageDeliveryEngine {
             return;
         this.ensurePeerContext();
         const ns = `message_class/${params.message_class}/${group ? params.volatile ? 'volatile_group' : 'group' : 'peer'}/${group ? params.group_id ?? params.group_aid : params.sender_aid}`;
-        if (this.automaticGroupPullStopped(ns))
+        if (this.automaticGroupPullStopped(ns) || this.oversizedPulls.has(ns))
             return;
         this.recordBackgroundPullNeed(ns, 0, true, true);
         this.backgroundPullNeeds.get(ns).messageClassRequest = { ...params };
@@ -1740,7 +1906,7 @@ export class MessageDeliveryEngine {
         }
     }
     recordBackgroundPullNeed(ns, throughSeq = 0, probe = false, restart = false) {
-        if (this.automaticGroupPullStopped(ns))
+        if (this.automaticGroupPullStopped(ns) || this.oversizedPulls.has(ns))
             return;
         const client = this.runtime.client;
         if (client._sessionOptions?.background_sync === false || !client._aid
@@ -1759,7 +1925,7 @@ export class MessageDeliveryEngine {
         need.probe ||= probe;
         this.backgroundPullNeeds.set(ns, need);
     }
-    observeBackgroundPullResponse(ns, afterSeq, result, limit = 50) {
+    observeBackgroundPullResponse(ns, afterSeq, result, limit = _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize) {
         if (!isJsonObject(result))
             return;
         const response = result;
@@ -1785,7 +1951,7 @@ export class MessageDeliveryEngine {
     finishBackgroundPull(ns, generation, afterSeq, failed, trigger) {
         if (generation !== this.captureInlineAckGeneration())
             return;
-        if (this.automaticGroupPullStopped(ns))
+        if (this.automaticGroupPullStopped(ns) || this.oversizedPulls.has(ns))
             return;
         const need = this.backgroundPullNeeds.get(ns);
         if (need && trigger && need.trigger !== trigger) {
@@ -1812,7 +1978,7 @@ export class MessageDeliveryEngine {
         this.requestBackgroundPullRecovery();
     }
     requestBackgroundPullRecovery() {
-        if (this.backgroundPullCheckQueued || (this.backgroundPullNeeds.size === 0 && !this.peerCatalogDirty && this.peerRecoveryNeeds.size === 0))
+        if (this.backgroundPullCheckQueued || (this.backgroundPullNeeds.size === 0 && !this.peerCatalogDirty && this.peerRecoveryNeeds.size === 0 && this.peerVolatileNeeds.size === 0))
             return;
         this.backgroundPullCheckQueued = true;
         const generation = this.captureInlineAckGeneration();
@@ -1824,6 +1990,8 @@ export class MessageDeliveryEngine {
             if (client._sessionOptions?.background_sync === false || client.state !== ConnectionState.READY || client._closing)
                 return;
             if (client._p2pPeerPullEnabled) {
+                if (this.peerVolatileNeeds.size && !this.peerVolatileTask)
+                    this.schedulePeerVolatileRecovery(this.peerVolatileNeeds.values().next().value);
                 if (this.peerCatalogDirty && !this.peerCatalogTask)
                     this.refreshPendingPeers();
                 for (const [sender, need] of this.peerRecoveryNeeds) {
@@ -1837,6 +2005,11 @@ export class MessageDeliveryEngine {
                     this.backgroundPullNeeds.delete(ns);
                     continue;
                 }
+                if (this.pendingV2GroupPulls.has(ns)) {
+                    if (!client._v2Session)
+                        continue;
+                    this.pendingV2GroupPulls.delete(ns);
+                }
                 if (ns.startsWith('p2p:') && !this.hasP2pApplicationSubscription())
                     continue;
                 if (need.messageClassRequest && need.messageClassRequest.message_class !== 'sdk_control') {
@@ -2262,6 +2435,8 @@ export class MessageDeliveryEngine {
             return applicationResult({ ...result, message_class: 'sdk_control' });
         if (!APP_SEND_ENVELOPE_METHODS.has(method) || !isJsonObject(result))
             return result;
+        if (result.status === 'echo_return')
+            return result;
         let out = { ...result };
         const serverEnvelope = method === 'group.send' && isJsonObject(out.envelope)
             ? { ...out.envelope }
@@ -2586,8 +2761,10 @@ export class MessageDeliveryEngine {
                 return this.runApplicationPage(namespace, source, async () => { await this.publishAppEvent(event, payload, source, deliveryContext); });
             }
         }
-        if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
-            client._maybeAppendEchoTraceReceive(payload);
+        if (source !== 'echo_return' && (event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
+            if (client._maybeAppendEchoTraceReceive(payload)) {
+                return client._returnReceivedEcho(payload);
+            }
         }
         this.logAppMessagePublish(event, payload, source);
         if (isJsonObject(payload)) {
@@ -2829,7 +3006,14 @@ export class MessageDeliveryEngine {
     }
     async onRawMessageReceived(data) {
         const client = this.runtime.client;
-        if (client._p2pPeerPullEnabled) {
+        if (isJsonObject(data) && !client._echoStarts.has(data))
+            client._echoStarts.set(data, performance.now());
+        const message = isJsonObject(data) ? data : undefined;
+        const payload = message?.payload;
+        const plainEcho = message && !message.encrypted && !message.encrypt && isJsonObject(payload)
+            && !String(payload.type ?? '').trim().toLowerCase().startsWith('e2ee') && !payload.ciphertext
+            && !client._isEncryptedPushMessage(message) && client._isEchoPayload(payload);
+        if (client._p2pPeerPullEnabled && !plainEcho) {
             await this.onPeerPush(data);
             return;
         }
@@ -2898,6 +3082,7 @@ export class MessageDeliveryEngine {
             return;
         }
         const msg = { ...data };
+        client._echoStarts.set(msg, client._echoStarts.get(data) ?? performance.now());
         if (!this.messageTargetsCurrentInstance(msg)) {
             client._clientLog.debug(`P2P push filtered by instance: message_id=${String(msg.message_id ?? '')}, seq=${String(msg.seq ?? '')}, target_device=${String(msg.device_id ?? '')}, target_slot=${String(msg.slot_id ?? '')}, local_device=${client._deviceId}, local_slot=${client._slotId}`);
             return;
@@ -2954,6 +3139,8 @@ export class MessageDeliveryEngine {
     }
     async onRawGroupMessageCreated(data) {
         const client = this.runtime.client;
+        if (isJsonObject(data) && !client._echoStarts.has(data))
+            client._echoStarts.set(data, performance.now());
         const tStart = Date.now();
         if (isJsonObject(data)) {
             client._logMessageDebug('server-push', '_raw.group.message_created', 'group.message_created', data);
@@ -2994,6 +3181,7 @@ export class MessageDeliveryEngine {
         }
         const msg = { ...data };
         const groupId = String(msg.group_id ?? '');
+        client._echoStarts.set(msg, client._echoStarts.get(data) ?? performance.now());
         const seq = msg.seq;
         const payload = msg.payload;
         if (groupId) {
@@ -3068,12 +3256,15 @@ export class MessageDeliveryEngine {
         const afterSeq = client._seqTracker.getContiguousSeq(ns);
         client._clientLog.debug(`auto pull group messages start: group=${groupId}, after_seq=${afterSeq}, seq=${String(notification.seq ?? '')}`);
         const operation = async () => {
-            const messages = await client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true, background: true });
+            let count;
+            const messages = await client._pullGroupV2(groupId, afterSeq, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, {
+                gateLocked: true, background: true, retainMessages: false, onMessageCount: (value) => { count = value; },
+            });
             this.prunePushedSeqs(ns);
-            return messages.length;
+            return count ?? messages.length;
         };
         if (client._rpcPipeline) {
-            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: 50 });
+            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize });
             await this.runAutomaticPull(ns, operation, (attempt) => client._rpcPipeline.runPullNamespaceSerialized(key, attempt, true));
         }
         else {
@@ -3107,9 +3298,9 @@ export class MessageDeliveryEngine {
         try {
             // Gap Fill 本身就是 Forward Pull，必须沿用协调器的完整事务：
             // 原始页提交成功后由协调器负责 Piggyback/终端 ACK。
-            const operation = () => client._pullV2(afterSeq, 50, { gateLocked: true });
+            const operation = () => client._pullV2(afterSeq, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, { gateLocked: true, background: true });
             const messages = await this.runAutomaticPull(ns, operation, (attempt) => client._rpcPipeline
-                ? client._rpcPipeline.runPullSerialized(client._rpcPipeline.pullGateKeyForCall('message.pull', { after_seq: afterSeq, limit: 50 }), attempt, true)
+                ? client._rpcPipeline.runPullSerialized(client._rpcPipeline.pullGateKeyForCall('message.pull', { after_seq: afterSeq, limit: _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize }), attempt, true)
                 : client._withBackgroundRpc(attempt));
             filled = messages.length;
             this.prunePushedSeqs(ns);
@@ -3149,11 +3340,14 @@ export class MessageDeliveryEngine {
         let filled = 0;
         let failed = false;
         try {
-            const operation = () => client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true, background: true });
+            let count;
+            const operation = () => client._pullGroupV2(groupId, afterSeq, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, {
+                gateLocked: true, background: true, retainMessages: false, onMessageCount: (value) => { count = value; },
+            });
             const messages = await this.runAutomaticPull(ns, operation, (attempt) => client._rpcPipeline
-                ? client._rpcPipeline.runPullNamespaceSerialized(client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: 50 }), attempt, true)
+                ? client._rpcPipeline.runPullNamespaceSerialized(client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize }), attempt, true)
                 : client._withBackgroundRpc(attempt));
-            filled = messages.length;
+            filled = count ?? messages.length;
             this.prunePushedSeqs(ns);
             client._clientLog.debug(`group message gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
@@ -3263,7 +3457,7 @@ export class MessageDeliveryEngine {
                     return;
                 if (generation !== this.captureInlineAckGeneration())
                     return;
-                this.observeBackgroundPullResponse(ns, nextAfterSeq, result);
+                this.observeBackgroundPullResponse(ns, nextAfterSeq, result, request.limit);
                 const events = result.events;
                 if (!Array.isArray(events))
                     return;
@@ -3355,12 +3549,15 @@ export class MessageDeliveryEngine {
                 if (eventObjects.length > 0 && ackContig > 0 && ackContig !== pageContigBefore) {
                     const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, ackContig);
                     try {
-                        const ackPromise = client._transport.call('group.ack_events', {
+                        const ackParams = {
                             group_id: groupId,
                             event_seq: ackSeq,
                             device_id: client._deviceId,
                             slot_id: client._slotId,
-                        }, undefined, undefined, true);
+                        };
+                        const ackPromise = !singlePage && client._rpcPipeline
+                            ? client._rpcPipeline.rawCall('group.ack_events', ackParams, { signed: false, background: true })
+                            : client._transport.call('group.ack_events', ackParams, undefined, undefined, true);
                         if (singlePage)
                             await ackPromise;
                         else
@@ -3716,7 +3913,7 @@ export class MessageDeliveryEngine {
             return requestedSeq;
         return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
     }
-    async runP2PRealtimeSync(ns, pushSeq, pageLimit = 50, forceTail = false) {
+    async runP2PRealtimeSync(ns, pushSeq, pageLimit = _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, forceTail = false) {
         const client = this.runtime.client;
         const before = this.syncState(ns);
         const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
@@ -3745,12 +3942,12 @@ export class MessageDeliveryEngine {
                     const tailResult = await client._v2E2EE.pullV2TailInternal({
                         window_mode: 'tail',
                         after_seq: after,
-                        limit: pageLimit,
+                        limit: Math.min(pageLimit, 50),
                     }, true);
                     tailHead = this.syncState(ns).head;
                     return tailResult;
                 }
-                const opts = { gateLocked: true };
+                const opts = { gateLocked: true, background };
                 if (request.max_pages !== undefined)
                     opts.maxPages = request.max_pages;
                 const messages = await client._pullV2(after, pageLimit, opts);
@@ -3762,7 +3959,7 @@ export class MessageDeliveryEngine {
             return await this.runAutomaticPull(ns, invoke, (attempt) => client._rpcPipeline.runPullSerialized(key, attempt, background));
         };
         if (order.length === 1 && order[0] === 'tail') {
-            result = await run({ window_mode: 'tail', after_seq: this.syncState(ns).ack, limit: pageLimit }, false);
+            result = await run({ window_mode: 'tail', after_seq: this.syncState(ns).ack, limit: Math.min(pageLimit, 50) }, false);
         }
         const state = this.syncState(ns);
         const needsForward = state.ack < state.tail - 1;
@@ -3793,7 +3990,7 @@ export class MessageDeliveryEngine {
         }
         return result;
     }
-    async runGroupRealtimeSync(groupId, ns, pushSeq, pageLimit = 50, forceTail = false) {
+    async runGroupRealtimeSync(groupId, ns, pushSeq, pageLimit = _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, forceTail = false) {
         const client = this.runtime.client;
         const before = this.syncState(ns);
         const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
@@ -3828,11 +4025,13 @@ export class MessageDeliveryEngine {
                     tailHead = this.syncState(ns).head;
                     return tailResult;
                 }
-                const opts = { gateLocked: true, background };
+                let count;
+                const opts = { gateLocked: true, background, retainMessages: !background,
+                    onMessageCount: (value) => { count = value; } };
                 if (request.max_pages !== undefined)
                     opts.maxPages = request.max_pages;
                 const messages = await client._pullGroupV2(groupId, after, pageLimit, opts);
-                return { messages, raw_count: messages.length };
+                return { messages, raw_count: count ?? messages.length };
             };
             if (!client._rpcPipeline)
                 return await this.runAutomaticPull(ns, invoke);
@@ -3874,7 +4073,7 @@ export class MessageDeliveryEngine {
         const client = this.runtime.client;
         const request = { after_seq: this.syncState(ns).ack, limit: pageLimit, max_pages: 1 };
         const invoke = async () => {
-            const messages = await client._pullV2(Number(request.after_seq), pageLimit, { gateLocked: true, maxPages: 1 });
+            const messages = await client._pullV2(Number(request.after_seq), pageLimit, { gateLocked: true, maxPages: 1, background });
             return { messages, raw_count: messages.length };
         };
         if (!client._rpcPipeline)
@@ -3888,8 +4087,11 @@ export class MessageDeliveryEngine {
         const maxPages = Math.max(1, Math.ceil(Math.max(0, throughSeq - ack) / pageLimit));
         const request = { group_id: groupId, after_seq: ack, limit: pageLimit, max_pages: maxPages };
         const invoke = async () => {
-            const messages = await client._pullGroupV2(groupId, Number(request.after_seq), pageLimit, { gateLocked: true, maxPages, background });
-            return { messages, raw_count: messages.length };
+            let count;
+            const messages = await client._pullGroupV2(groupId, Number(request.after_seq), pageLimit, {
+                gateLocked: true, maxPages, background, retainMessages: !background, onMessageCount: (value) => { count = value; },
+            });
+            return { messages, raw_count: count ?? messages.length };
         };
         if (!client._rpcPipeline)
             return await this.runAutomaticPull(ns, invoke);
@@ -4097,7 +4299,7 @@ export class MessageDeliveryEngine {
         if (!this.beginRealtimeSync(ns))
             return;
         try {
-            await this.runP2PRealtimeSync(ns, this.syncState(ns).head, 50, true);
+            await this.runP2PRealtimeSync(ns, this.syncState(ns).head, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, true);
         }
         catch (exc) {
             client._clientLog.warn(`V2 P2P invalid-seq Tail failed: ${formatDeliveryError(exc)}`);
@@ -4112,7 +4314,7 @@ export class MessageDeliveryEngine {
         if (!this.beginRealtimeSync(ns))
             return;
         try {
-            await this.runGroupRealtimeSync(groupId, ns, this.syncState(ns).head, 50, true);
+            await this.runGroupRealtimeSync(groupId, ns, this.syncState(ns).head, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, true);
         }
         catch (exc) {
             client._clientLog.warn(`V2 group invalid-seq Tail failed: group=${groupId} ${formatDeliveryError(exc)}`);
@@ -4692,7 +4894,7 @@ export class MessageDeliveryEngine {
         }
         let pullFailed = false;
         try {
-            await this.runP2PRealtimeSync(ns, pushSeq, 50, false);
+            await this.runP2PRealtimeSync(ns, pushSeq, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, false);
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                 return;
             // Tail 期间新到达的 Push 已由 realtime sync 在同一周期内补至多一页 Forward。
@@ -4729,7 +4931,7 @@ export class MessageDeliveryEngine {
             const coordinator = client._v2E2EE;
             const pendingAckSeq = Number(coordinator.pendingForwardAck?.(ns, committedAck) ?? 0);
             if (pendingAckSeq > 0) {
-                client._safeAsync(coordinator.confirmForwardGroupAck(groupId, pendingAckSeq, String(data.group_aid ?? '').trim() || undefined, true));
+                this.scheduleForwardAck(ns, pendingAckSeq, seq => coordinator.confirmForwardGroupAck(groupId, seq, String(data.group_aid ?? '').trim() || undefined, true));
             }
             else {
                 const pendingNs = this.resolvePendingGroupInlineAckNamespace(ns);
@@ -4755,7 +4957,7 @@ export class MessageDeliveryEngine {
                 while (true) {
                     const ackBefore = this.syncState(ns).ack;
                     attemptAfterSeq = ackBefore;
-                    await this.runGroupForwardRecovery(groupId, ns, 50, true, targets.get(ns) ?? 0);
+                    await this.runGroupForwardRecovery(groupId, ns, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, true, targets.get(ns) ?? 0);
                     const ackAfter = this.syncState(ns).ack;
                     if (ackAfter >= (targets.get(ns) ?? 0) || ackAfter <= ackBefore)
                         return;
@@ -4790,8 +4992,6 @@ export class MessageDeliveryEngine {
         const groupId = typeof d.group_id === 'string' ? d.group_id.trim() : '';
         const rawSeq = d.seq;
         const inlinePresent = hasNonEmptyInlineMessage(d.inline_message);
-        if (!client._v2Session && !(expectedVersion === 'v1' && inlinePresent))
-            return;
         const seq = this.realtimeHeadSeq(rawSeq, inlinePresent);
         if (!groupId) {
             client._clientLog.debug(`_onRawGroupV2MessageCreated skipped: group=${groupId || '<empty>'}, seq=${String(d.seq ?? '')}`);
@@ -4804,6 +5004,15 @@ export class MessageDeliveryEngine {
             return;
         }
         const eventKind = String(d.kind ?? '').trim();
+        if (!client._v2Session && !(expectedVersion === 'v1' && inlinePresent)) {
+            if (client._sessionOptions?.background_sync !== false) {
+                const ns = `group:${groupId}`;
+                this.recordBackgroundPullNeed(ns, seq, eventKind === 'group.online_unread_hint', true);
+                if (this.backgroundPullNeeds.has(ns))
+                    this.pendingV2GroupPulls.add(ns);
+            }
+            return;
+        }
         if (eventKind === 'group.online_unread_hint') {
             if (client._sessionOptions.background_sync === false)
                 return;
@@ -4852,7 +5061,7 @@ export class MessageDeliveryEngine {
             return;
         }
         let pullFailed = false;
-        void this.runGroupRealtimeSync(groupId, ns, seq, 50, false).then(async () => {
+        void this.runGroupRealtimeSync(groupId, ns, seq, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, false).then(async () => {
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                 return;
             // Tail 期间新到达的 Push 已由 realtime sync 在同一周期内补至多一页 Forward。
@@ -4938,18 +5147,44 @@ export class MessageDeliveryEngine {
             this.refreshPendingPeers();
             return;
         }
-        if (!client._aid || !client._v2Session)
+        if (!client._aid || !client._v2Session || client._sessionOptions?.background_sync === false)
             return;
         const ns = `p2p:${client._aid}`;
         const generation = this.captureInlineAckGeneration();
-        const afterSeq = this.syncState(ns).ack;
-        this.recordBackgroundPullNeed(ns, positiveSafeSequenceHint(data.seq), true, true);
+        const state = this.syncState(ns);
+        const afterSeq = state.ack;
+        const hintSeq = positiveSafeSequenceHint(data.seq);
+        if (hintSeq > 0 && afterSeq >= Math.max(hintSeq, state.head, Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0), Number(client._pendingP2pPullUpper?.get?.(ns) ?? 0))
+            && afterSeq >= state.tail - 1 && !client._pendingOrderedMsgs.get(ns)?.size) {
+            const coordinator = client._v2E2EE;
+            const pendingAckSeq = Number(coordinator.pendingForwardAck?.(ns, afterSeq) ?? 0);
+            if (pendingAckSeq > 0) {
+                this.scheduleForwardAck(ns, pendingAckSeq, seq => coordinator.confirmForwardP2PAck(seq));
+            }
+            else {
+                const pending = this.pendingP2PInlineAcks?.get(ns);
+                if (pending)
+                    this.retryPendingP2PInlineAck(ns, pending.seq, 'covered online hint', afterSeq);
+            }
+            return;
+        }
+        this.recordBackgroundPullNeed(ns, hintSeq, true, true);
         const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
+        const tasks = this.onlineUnreadHintTasks ?? new Map();
+        this.onlineUnreadHintTasks = tasks;
+        if (tasks.has(ns))
+            return;
         let failed = false;
-        client._safeAsync(this.runP2PForwardRecovery(ns, 50, true).catch((exc) => {
+        const task = this.runP2PForwardRecovery(ns, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, true).then(() => undefined).catch((exc) => {
             failed = true;
             client._clientLog.debug(`P2P online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-        }).finally(() => this.finishBackgroundPull(ns, generation, afterSeq, failed, pullTrigger)));
+        }).finally(() => {
+            if (tasks.get(ns) === task)
+                tasks.delete(ns);
+            this.finishBackgroundPull(ns, generation, afterSeq, failed, pullTrigger);
+        });
+        tasks.set(ns, task);
+        client._safeAsync(task);
     }
     async saveSeqTrackerState() {
         const client = this.runtime.client;