@agentunion/fastaun 0.5.10 → 0.5.12

package/dist/client/delivery.js

@@ -50,6 +50,10 @@ function positiveSafeSequenceHint(value) {
     const parsed = Number(value);
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
 }
+function hasNonEmptyInlineMessage(value) {
+    return isJsonObject(value)
+        && Object.keys(value).length > 0;
+}
 function nonNegativeSafeSequenceHint(value) {
     return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
 }
@@ -80,6 +84,8 @@ export class MessageDeliveryEngine {
     inlineAckGeneration = 0;
     pendingDeliveryChanges = null;
     deliveryChangedGeneration = 0;
+    syncRun = 0;
+    syncSessions = null;
     // 同一实例的 tracker 写入必须串行，避免旧的延迟 flush 覆盖新的 Forward 提交。
     seqTrackerWriteChain = Promise.resolve();
     constructor(runtime) {
@@ -152,6 +158,7 @@ export class MessageDeliveryEngine {
         }
         const client = this.runtime.client;
         this.ensurePullOperationCurrent();
+        this.syncStarted(ns);
         const response = result;
         const messages = deduplicatePlainForwardPageMessages(response.messages, afterSeq);
         const coordinator = this.forwardCoordinator();
@@ -194,20 +201,24 @@ export class MessageDeliveryEngine {
                 }
                 const message = normalizeGroupMentionMode(rawMessage);
                 if (this.recallEventFromGroupMessage(message)) {
-                    if (await this.publishGroupRecallTombstone(groupId, seq, message)) {
+                    if (await this.publishGroupRecallTombstone(groupId, seq, message, 'pull')) {
                         this.ensurePullOperationCurrent();
                         this.markPublishedSeq(ns, seq);
                         publishedCount += 1;
                     }
                 }
+                else if (this.isSelfSentGroupMessage(message)) {
+                    this.markPublishedSeq(ns, seq);
+                }
                 else if (await this.publishPulledMessage('group.message_created', ns, seq, message, false)) {
                     this.ensurePullOperationCurrent();
                     publishedCount += 1;
                 }
             }
             this.ensurePullOperationCurrent();
-            if (messages.length > 0)
-                client._seqTracker.onPullResult(ns, messages, afterSeq);
+            client._seqTracker.onPullResult(ns, messages, afterSeq, Number.isSafeInteger(result.contiguous_seq)
+                ? result.contiguous_seq
+                : undefined);
             const commitTarget = Math.max(client._seqTracker.getContiguousSeq(ns), retentionFloor, visibilityFloor, deferredServerCursor);
             if (commitTarget > client._seqTracker.getContiguousSeq(ns)) {
                 client._seqTracker.forceContiguousSeq(ns, commitTarget);
@@ -261,9 +272,17 @@ export class MessageDeliveryEngine {
             this.ensurePullOperationCurrent();
             await this.confirmPlainForwardAck(ns, ackMethod, pendingAckSeq, groupId);
         }
+        this.syncProgress(ns, {
+            rawCount: messages.length,
+            pulledCount: publishedCount,
+            remaining: response.remaining,
+            hasMore: typeof response.has_more === 'boolean' ? response.has_more : undefined,
+            currentSeq: client._seqTracker.getContiguousSeq(ns),
+        });
         return { rawCount: messages.length, publishedCount };
     }
     resetInlineAckState() {
+        this.syncStopped('aborted');
         this.deliveryChangedGeneration += 1;
         this.pendingDeliveryChanges = null;
         this.inlineAckGeneration += 1;
@@ -276,6 +295,7 @@ export class MessageDeliveryEngine {
         this.onlineUnreadHintTargets = null;
         this.onlineUnreadHintTasks = null;
         this.realtimeTailHeads = null;
+        this.syncSessions = null;
     }
     deliveryChangedNamespace(event, payload) {
         if (event === 'group.message_created' && isJsonObject(payload)) {
@@ -301,9 +321,9 @@ export class MessageDeliveryEngine {
             || (typeof seq === 'number' && Number.isSafeInteger(seq) && seq > 0);
     }
     deliveryChangedTrigger(source) {
-        if (source === 'inline-push')
+        if (source === 'inline-push' || source === 'inline_push')
             return 'inline_push';
-        if (source === 'pull' || source === 'tail')
+        if (source === 'pull' || source === 'tail' || source === 'pending-retry' || source === 'pending_retry')
             return 'pull_drained';
         if (source === 'push' || source === 'group-push' || source === 'ordered')
             return 'push';
@@ -336,7 +356,7 @@ export class MessageDeliveryEngine {
         pending.clear();
         if (changes.length === 0)
             return;
-        const payload = { trigger, changes };
+        const payload = { source: trigger === 'pull_drained' ? 'pull' : trigger, trigger, changes };
         const dispatcher = this.runtime.client._dispatcher;
         const published = typeof dispatcher.enqueue === 'function'
             ? (dispatcher.enqueue('delivery.changed', payload), undefined)
@@ -348,8 +368,119 @@ export class MessageDeliveryEngine {
                 this.runtime.client._clientLog.warn(`delivery.changed handler failed: ${formatDeliveryError(exc)}`);
             });
     }
+    publishSyncLifecycle(event, payload) {
+        const dispatcher = this.runtime.client._dispatcher;
+        const published = typeof dispatcher.enqueue === 'function'
+            ? (dispatcher.enqueue(event, payload), undefined)
+            : typeof dispatcher.publishSyncAware === 'function'
+                ? dispatcher.publishSyncAware(event, payload)
+                : dispatcher.publish?.(event, payload);
+        if (isPromiseLike(published))
+            void Promise.resolve(published).catch((exc) => {
+                this.runtime.client._clientLog.warn(`${event} handler failed: ${formatDeliveryError(exc)}`);
+            });
+    }
+    syncStarted(ns) {
+        const namespace = String(ns ?? '').trim();
+        if (!namespace)
+            return;
+        const sessions = this.syncSessions ?? new Map();
+        this.syncSessions = sessions;
+        if (sessions.has(namespace))
+            return;
+        if (sessions.size === 0) {
+            this.syncRun += 1;
+            this.publishSyncLifecycle('sync.started', {
+                run_id: this.syncRun,
+                source: 'pull',
+                syncing: true,
+                namespaces_pending: 1,
+                received_total: 0,
+                namespace,
+                started_at: Date.now(),
+            });
+        }
+        const session = { pages: 0, pulled: 0, startedAt: Date.now() };
+        sessions.set(namespace, session);
+    }
+    syncProgress(ns, progress = {}) {
+        const namespace = String(ns ?? '').trim();
+        if (!namespace)
+            return;
+        this.syncStarted(namespace);
+        const session = this.syncSessions?.get(namespace);
+        if (!session)
+            return;
+        const pulledCount = Math.max(0, Number(progress.pulledCount ?? progress.rawCount ?? 0) || 0);
+        const rawCount = Math.max(0, Number(progress.rawCount ?? pulledCount) || 0);
+        session.pages += 1;
+        session.pulled += pulledCount;
+        const payload = {
+            run_id: this.syncRun,
+            source: 'pull',
+            namespace,
+            page: session.pages,
+            page_pulled_count: pulledCount,
+            page_raw_count: rawCount,
+            pulled_count: session.pulled,
+            received_total: session.pulled,
+            batch_size: pulledCount,
+        };
+        if (typeof progress.remaining === 'number'
+            && Number.isSafeInteger(progress.remaining) && progress.remaining >= 0) {
+            payload.remaining = progress.remaining;
+            payload.estimated_remaining = payload.remaining;
+        }
+        if (progress.hasMore !== undefined) {
+            payload.has_more = Boolean(progress.hasMore);
+            if (progress.remaining === undefined || progress.remaining === null) {
+                payload.estimated_remaining = progress.hasMore ? undefined : 0;
+            }
+        }
+        if (progress.currentSeq !== undefined && Number.isFinite(Number(progress.currentSeq))) {
+            payload.current_seq = Math.max(0, Number(progress.currentSeq));
+        }
+        if (progress.targetSeq !== undefined && Number.isFinite(Number(progress.targetSeq))) {
+            payload.target_seq = Math.max(0, Number(progress.targetSeq));
+        }
+        this.publishSyncLifecycle('sync.progress', payload);
+    }
     onPullDrained() {
         this.flushDeliveryChanged('pull_drained');
+        this.syncStopped('pull_drained');
+    }
+    onPullAborted() {
+        this.syncStopped('aborted');
+    }
+    syncStopped(reason = 'completed') {
+        const sessions = this.syncSessions;
+        if (!sessions || sessions.size === 0)
+            return;
+        const entries = [...sessions.entries()];
+        const receivedTotal = entries.reduce((total, [, session]) => total + session.pulled, 0);
+        const payload = {
+            run_id: this.syncRun,
+            source: 'pull',
+            syncing: false,
+            namespaces_pending: 0,
+            received_total: receivedTotal,
+            reason,
+            stopped_at: Date.now(),
+        };
+        if (entries.length === 1) {
+            const [namespace, session] = entries[0];
+            payload.namespace = namespace;
+            payload.pages = session.pages;
+            payload.pulled_count = session.pulled;
+        }
+        else {
+            payload.namespaces = entries.map(([namespace]) => namespace);
+            payload.pages = entries.reduce((total, [, session]) => total + session.pages, 0);
+            payload.pulled_count = receivedTotal;
+        }
+        sessions.clear();
+        this.syncSessions = null;
+        this.publishSyncLifecycle('sync.stopped', payload);
     }
     flushDeliveryChangedContext(context, trigger) {
         if (context.generation !== this.deliveryChangedGeneration || context.changes.size === 0)
@@ -369,7 +500,7 @@ export class MessageDeliveryEngine {
         if (changes.length === 0)
             return;
         const dispatcher = this.runtime.client._dispatcher;
-        const payload = { trigger, changes };
+        const payload = { trigger, source: trigger, changes };
         const published = typeof dispatcher.enqueue === 'function'
             ? (dispatcher.enqueue('delivery.changed', payload), undefined)
             : typeof dispatcher.publishSyncAware === 'function'
@@ -431,6 +562,9 @@ export class MessageDeliveryEngine {
     hasPendingPull(ns) {
         return (this.pendingGroupPullUpper?.get(ns) ?? 0) > 0;
     }
+    pendingPullUpper(ns) {
+        return this.pendingGroupPullUpper?.get(ns) ?? 0;
+    }
     hasAnyPendingPull() {
         return [...(this.pendingGroupPullUpper?.values() ?? [])].some((seq) => seq > 0)
             || Boolean(this.onlineUnreadHintTasks?.size)
@@ -527,7 +661,7 @@ export class MessageDeliveryEngine {
             return;
         }
         if (event === 'message.recalled') {
-            await this.publishMessageRecallTombstone(seq, payload);
+            await this.publishMessageRecallTombstone(seq, payload, source);
             this.ensurePullOperationCurrent();
             return;
         }
@@ -580,17 +714,27 @@ export class MessageDeliveryEngine {
         }
         return result;
     }
-    normalizePublishedMessagePayload(event, payload) {
+    normalizePublishedMessagePayload(event, payload, source = 'direct') {
         payload = this.stripInlineInternalFields(payload);
+        let normalized;
         if (this.isInstanceScopedMessageEvent(event)) {
             if (event === 'group.message_created')
                 payload = normalizeGroupMentionMode(payload);
-            return this.attachAppMessageEnvelope(this.stripInternalSenderDeviceFields(this.attachCurrentInstanceContext(payload)));
+            normalized = this.attachAppMessageEnvelope(this.stripInternalSenderDeviceFields(this.attachCurrentInstanceContext(payload)));
+        }
+        else if (this.isGroupScopedEvent(event)) {
+            normalized = this.attachAppGroupEventEnvelope(this.attachCurrentInstanceContext(payload));
         }
-        if (this.isGroupScopedEvent(event)) {
-            return this.attachAppGroupEventEnvelope(this.attachCurrentInstanceContext(payload));
+        else {
+            normalized = payload;
         }
-        return payload;
+        if (source === 'direct' || !isJsonObject(normalized))
+            return normalized;
+        const canonicalSource = source === 'group-push' || source === 'ordered' || source === 'legacy' || source === 'tail'
+            ? (source === 'tail' ? 'pull' : 'push')
+            : source === 'inline-push' || source === 'inline_push' ? 'inline_push'
+                : source === 'pending-retry' || source === 'pending_retry' ? 'pending_retry' : source;
+        return { ...normalized, source: canonicalSource };
     }
     stripInlineInternalFields(payload) {
         if (!isJsonObject(payload))
@@ -860,7 +1004,7 @@ export class MessageDeliveryEngine {
             return `p2p|tombstone:${tombstoneId}`;
         return `p2p|unknown:${Date.now()}:${Math.random()}`;
     }
-    async publishMessageRecallTombstone(seq, message) {
+    async publishMessageRecallTombstone(seq, message, source = 'push') {
         const client = this.runtime.client;
         const eventPayload = this.recallEventFromMessage(message);
         if (!eventPayload)
@@ -881,7 +1025,7 @@ export class MessageDeliveryEngine {
             for (const [oldKey] of drop)
                 seen.delete(oldKey);
         }
-        await client._publishAppEvent('message.recalled', eventPayload, 'message-recall');
+        await client._publishAppEvent('message.recalled', eventPayload, source);
         client._clientLog.debug(`message.recalled published: seq=${String(seq)} ids=${JSON.stringify(eventPayload.message_ids)}`);
         return true;
     }
@@ -964,7 +1108,7 @@ export class MessageDeliveryEngine {
             return `${normalizedGroupId}|tombstone:${tombstoneId}`;
         return `${normalizedGroupId}|unknown:${Date.now()}:${Math.random()}`;
     }
-    async publishGroupRecallTombstone(groupId, seq, message) {
+    async publishGroupRecallTombstone(groupId, seq, message, source = 'push') {
         const client = this.runtime.client;
         const eventPayload = this.recallEventFromGroupMessage(message);
         if (!eventPayload)
@@ -987,7 +1131,7 @@ export class MessageDeliveryEngine {
             for (const [oldKey] of drop)
                 seen.delete(oldKey);
         }
-        await client._publishAppEvent('group.message_recalled', eventPayload, 'group-recall');
+        await client._publishAppEvent('group.message_recalled', eventPayload, source);
         client._clientLog.debug(`group.message_recalled published: group=${groupId} seq=${String(seq)} ids=${JSON.stringify(eventPayload.message_ids)}`);
         return true;
     }
@@ -1027,35 +1171,11 @@ export class MessageDeliveryEngine {
             return;
         }
         const ns = `group:${groupId}`;
-        if (seqNum > 0) {
+        if (seqNum > 0)
             client._seqTracker.updateMaxSeen(ns, seqNum);
-            if (client._seqTracker.getContiguousSeq(ns) === seqNum) {
-                // 已覆盖（pull 先到并推进过），仍走去重发布兜底，不重复推进 seq。
-                await this.publishGroupRecallTombstone(groupId, seq, wrapped);
-                return;
-            }
-            client._repairPushContiguousBound(ns, seqNum, true, '_raw.group.message_recalled');
-        }
-        // 该 notice_seq 已由 pull 路径处理过（已发布或挂起待发布）时，去重发布兜底后返回。
-        const pushed = client._pushedSeqs.get(ns);
-        const pending = client._pendingOrderedMsgs.get(ns);
-        if (pushed?.has(seqNum) || pending?.has(seqNum)) {
-            await this.publishGroupRecallTombstone(groupId, seq, wrapped);
-            return;
+        if (seqNum > client._seqTracker.getContiguousSeq(ns) && client._sessionOptions?.background_sync !== false) {
+            this.fillGroupGap(groupId).catch((exc) => client._clientLog.warn(`background recall gap fill failed: ${formatDeliveryError(exc)}`));
         }
-        const contigBefore = client._seqTracker.getContiguousSeq(ns);
-        client._seqTracker.onMessageSeq(ns, seqNum);
-        await this.publishGroupRecallTombstone(groupId, seq, wrapped);
-        this.markPublishedSeq(ns, seqNum);
-        client._markOrderedSeqDelivered?.(ns, seqNum);
-        const contig = client._seqTracker.getContiguousSeq(ns);
-        if (contig > 0) {
-            const ackSeq = this.clampAckSeq('group.ack_messages', 'msg_seq', ns, contig);
-            client._withBackgroundRpc(() => client._ackGroupV2(groupId, ackSeq))
-                .catch((e) => { client._clientLog.debug(`group recall auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`); });
-        }
-        if (contig !== contigBefore)
-            this.persistSeq(ns);
     }
     publishAppEvent(event, payload, source = 'direct', deliveryContext) {
         const client = this.runtime.client;
@@ -1078,7 +1198,7 @@ export class MessageDeliveryEngine {
             }
         }
         const generation = this.deliveryChangedGeneration;
-        const normalized = this.normalizePublishedMessagePayload(event, payload);
+        const normalized = this.normalizePublishedMessagePayload(event, payload, source);
         const dispatcher = client._dispatcher;
         const result = typeof dispatcher.enqueue === 'function'
             ? (dispatcher.enqueue(event, normalized), undefined)
@@ -1197,6 +1317,21 @@ export class MessageDeliveryEngine {
         }
         return true;
     }
+    isSelfSentGroupMessage(message) {
+        if (!isJsonObject(message))
+            return false;
+        const client = this.runtime.client;
+        const selfAid = String(client._aid ?? '').trim().toLowerCase();
+        const senderAid = String(message.sender_aid ?? message.from_aid ?? message.from ?? '').trim().toLowerCase();
+        if (!selfAid || senderAid !== selfAid)
+            return false;
+        const senderDevice = Object.prototype.hasOwnProperty.call(message, 'sender_device_id')
+            ? message.sender_device_id
+            : message.from_device_id;
+        if (typeof senderDevice !== 'string' || !senderDevice.trim() || !String(client._deviceId ?? '').trim())
+            return false;
+        return senderDevice.trim() === String(client._deviceId).trim();
+    }
     async runPushProcessSerialized(ns, operation, inlineGeneration) {
         const client = this.runtime.client;
         if (inlineGeneration === undefined) {
@@ -1264,7 +1399,7 @@ export class MessageDeliveryEngine {
             ? `p2p:${client._aid}`
             : '';
         const inlineGeneration = isJsonObject(data)
-            && Object.prototype.hasOwnProperty.call(data, 'inline_message')
+            && hasNonEmptyInlineMessage(data.inline_message)
             ? this.captureInlineAckGeneration() : undefined;
         this.runPushProcessSerialized(ns, () => this.processAndPublishMessage(data, inlineGeneration), inlineGeneration).catch((exc) => {
             client._clientLog.warn(`P2P message decrypt failed: ${formatDeliveryError(exc)}`);
@@ -1279,7 +1414,7 @@ export class MessageDeliveryEngine {
                     _decrypt_error: String(exc),
                 };
                 client._attachV2EnvelopeMetadataFromSource(safeEvent, data);
-                Promise.resolve(client._publishAppEvent('message.undecryptable', safeEvent)).catch(() => { });
+                Promise.resolve(client._publishAppEvent('message.undecryptable', safeEvent, 'push')).catch(() => { });
             }
         });
         client._clientLog.debug(`_onRawMessageReceived exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
@@ -1299,20 +1434,9 @@ export class MessageDeliveryEngine {
             const seqNum = Number(seq);
             if (Number.isFinite(seqNum) && seqNum > 0)
                 client._seqTracker.updateMaxSeen(ns, seqNum);
-            const contigBefore = client._seqTracker.getContiguousSeq(ns);
-            const published = await this.publishOrderedMessage('message.recalled', ns, seq, msg);
-            const contigAfter = client._seqTracker.getContiguousSeq(ns);
-            if (Number(seq) > contigAfter && !published && client._sessionOptions?.background_sync !== false) {
+            if (Number(seq) > client._seqTracker.getContiguousSeq(ns) && client._sessionOptions?.background_sync !== false) {
                 this.fillP2pGap().catch((exc) => client._clientLog.warn(`background recall gap fill failed: ${formatDeliveryError(exc)}`));
             }
-            const contig = client._seqTracker.getContiguousSeq(ns);
-            if (contig > 0) {
-                const ackSeq = this.clampAckSeq('message.ack', 'seq', ns, contig);
-                client._withBackgroundRpc(() => client._ackV2(ackSeq))
-                    .catch((e) => { client._clientLog.debug(`P2P recall auto-ack failed: ${formatDeliveryError(e)}`); });
-            }
-            if (contigAfter !== contigBefore)
-                this.persistSeq(ns);
             return;
         }
         await this.publishMessageRecallTombstone(seq, msg);
@@ -1331,7 +1455,7 @@ export class MessageDeliveryEngine {
         // 新 SDK 的所有带合法 seq P2P Push 都只作为 Head 通知处理。
         // 新服务端为兼容旧 SDK 仍可能发送 message.received；V2 会话下必须
         // 在旧 seq tracking / ordered publish 之前转入前台 Tail 协调器。
-        const inlinePresent = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
+        const inlinePresent = hasNonEmptyInlineMessage(msg.inline_message);
         const legacyPushSeq = this.realtimeHeadSeq(msg.seq, inlinePresent);
         if (client._v2Session && client._aid && (msg.seq !== undefined && msg.seq !== null || inlinePresent)) {
             if (legacyPushSeq === null) {
@@ -1350,29 +1474,11 @@ export class MessageDeliveryEngine {
             const ns = `p2p:${client._aid}`;
             if (seq > 0)
                 client._seqTracker.updateMaxSeen(ns, seq);
-            const contigBefore = client._seqTracker.getContiguousSeq(ns);
-            const published = encryptedPush
-                ? await client._publishEncryptedPushMessage('message.received', 'message.undecryptable', ns, seq, msg, false)
-                : await this.publishOrderedMessage('message.received', ns, seq, msg);
-            const contigAfter = client._seqTracker.getContiguousSeq(ns);
-            const needPull = Number(seq) > contigAfter && !published;
-            if (needPull && client._sessionOptions?.background_sync !== false) {
-                client._clientLog.debug(`P2P seq gap detected: ns=${ns}, seq=${seq}, contiguous=${contigAfter}`);
+            if (Number(seq) > client._seqTracker.getContiguousSeq(ns) && client._sessionOptions?.background_sync !== false) {
+                client._clientLog.debug(`P2P push triggering Forward: ns=${ns}, seq=${seq}, contiguous=${client._seqTracker.getContiguousSeq(ns)}`);
                 this.fillP2pGap().catch((exc) => client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`));
             }
-            const contig = client._seqTracker.getContiguousSeq(ns);
-            if (contig > 0) {
-                const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
-                const ackSeq = this.clampAckSeq('message.ack', 'seq', ns, contig);
-                client._clientLog.debug(`P2P push auto-ack send: ns=${ns}, seq=${ackSeq}, contiguous=${contig}, max_seen=${maxSeen}`);
-                client._withBackgroundRpc(() => client._ackV2(ackSeq))
-                    .then(() => { client._clientLog.debug(`P2P push auto-ack ok: ns=${ns}, seq=${ackSeq}`); })
-                    .catch((e) => { client._clientLog.debug(`P2P auto-ack failed: ${formatDeliveryError(e)}`); });
-            }
-            if (contigAfter !== contigBefore)
-                this.persistSeq(ns);
-            if (encryptedPush)
-                return;
+            return;
         }
         else {
             if (encryptedPush) {
@@ -1396,7 +1502,7 @@ export class MessageDeliveryEngine {
             ? String(data.group_id ?? '').trim()
             : '';
         const inlineGeneration = isJsonObject(data)
-            && Object.prototype.hasOwnProperty.call(data, 'inline_message')
+            && hasNonEmptyInlineMessage(data.inline_message)
             ? this.captureInlineAckGeneration() : undefined;
         this.runPushProcessSerialized(groupNs ? `group:${groupNs}` : '', () => this.processAndPublishGroupMessage(data, inlineGeneration), inlineGeneration).catch((exc) => {
             client._clientLog.warn(`group message decrypt failed: ${formatDeliveryError(exc)}`);
@@ -1411,7 +1517,7 @@ export class MessageDeliveryEngine {
                     _decrypt_error: String(exc),
                 };
                 client._attachV2EnvelopeMetadataFromSource(safeEvent, data);
-                Promise.resolve(client._publishAppEvent('group.message_undecryptable', safeEvent)).catch(() => { });
+                Promise.resolve(client._publishAppEvent('group.message_undecryptable', safeEvent, 'push')).catch(() => { });
             }
         });
         client._clientLog.debug(`_onRawGroupMessageCreated exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
@@ -1431,7 +1537,7 @@ export class MessageDeliveryEngine {
         }
         // V2 会话中旧 group.message_created 也只是 Head 通知；必须先 Tail，
         // 不能让 payload 路径直接推进旧 ordered publish 状态。
-        const inlinePresent = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
+        const inlinePresent = hasNonEmptyInlineMessage(msg.inline_message);
         const legacyPushSeq = this.realtimeHeadSeq(seq, inlinePresent);
         if (client._v2Session && groupId && (seq !== undefined && seq !== null || inlinePresent)) {
             if (legacyPushSeq === null) {
@@ -1456,46 +1562,15 @@ export class MessageDeliveryEngine {
             const ns = `group:${groupId}`;
             if (seq > 0)
                 client._seqTracker.updateMaxSeen(ns, seq);
-            const contigBefore = client._seqTracker.getContiguousSeq(ns);
-            // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled，仍占 seq 推进 contiguous/ack。
-            if (!encryptedPush && this.recallEventFromGroupMessage(msg)) {
-                const published = await this.publishOrderedGroupRecall(ns, seq, msg);
-                const contigAfter = client._seqTracker.getContiguousSeq(ns);
-                const contig = client._seqTracker.getContiguousSeq(ns);
-                if (contig > 0) {
-                    const ackSeq = this.clampAckSeq('group.ack_messages', 'msg_seq', ns, contig);
-                    client._withBackgroundRpc(() => client._ackGroupV2(groupId, ackSeq))
-                        .catch((e) => { client._clientLog.debug(`group recall auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`); });
-                }
-                if (contigAfter !== contigBefore)
-                    this.persistSeq(ns);
-                void published;
-                return;
-            }
-            const published = encryptedPush
-                ? await client._publishEncryptedPushMessage('group.message_created', 'group.message_undecryptable', ns, seq, msg, true)
-                : await this.publishOrderedMessage('group.message_created', ns, seq, msg);
-            const contigAfter = client._seqTracker.getContiguousSeq(ns);
-            const needPull = Number(seq) > contigAfter && !published;
-            if (needPull && client._sessionOptions?.background_sync !== false) {
-                client._clientLog.debug(`group message seq gap detected: group=${groupId}, seq=${seq}, contiguous=${contigAfter}`);
+            if (Number(seq) > client._seqTracker.getContiguousSeq(ns) && client._sessionOptions?.background_sync !== false) {
+                client._clientLog.debug(`group push triggering Forward: group=${groupId}, seq=${seq}, contiguous=${client._seqTracker.getContiguousSeq(ns)}`);
                 this.fillGroupGap(groupId).catch((exc) => client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`));
             }
-            const contig = client._seqTracker.getContiguousSeq(ns);
-            if (contig > 0) {
-                const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
-                const ackSeq = this.clampAckSeq('group.ack_messages', 'msg_seq', ns, contig);
-                client._clientLog.debug(`group push auto-ack send: group=${groupId}, ns=${ns}, seq=${ackSeq}, contiguous=${contig}, max_seen=${maxSeen}`);
-                client._withBackgroundRpc(() => client._ackGroupV2(groupId, ackSeq))
-                    .then(() => { client._clientLog.debug(`group push auto-ack ok: group=${groupId}, seq=${ackSeq}`); })
-                    .catch((e) => { client._clientLog.debug(`group message auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`); });
-            }
-            if (contigAfter !== contigBefore)
-                this.persistSeq(ns);
-            if (encryptedPush)
-                return;
+            return;
         }
         else {
+            if (this.isSelfSentGroupMessage(msg))
+                return;
             if (encryptedPush) {
                 await client._publishEncryptedPushMessage('group.message_created', 'group.message_undecryptable', '', seq ?? 0, msg, true);
                 return;
@@ -1507,7 +1582,7 @@ export class MessageDeliveryEngine {
         const client = this.runtime.client;
         let groupId = String(notification.group_id ?? '').trim();
         if (!groupId) {
-            await client._publishAppEvent('group.message_created', notification);
+            await client._publishAppEvent('group.message_created', notification, 'push');
             return;
         }
         if (client._sessionOptions?.background_sync === false) {
@@ -1657,8 +1732,10 @@ export class MessageDeliveryEngine {
             }
         }
         client._gapFillDone.set(dedupKey, Date.now());
+        this.syncStarted(ns);
         let filled = 0;
         let continuationAfterSeq = 0;
+        let failed = false;
         try {
             let nextAfterSeq = afterSeq;
             const maxPages = singlePage ? 1 : 100;
@@ -1689,9 +1766,9 @@ export class MessageDeliveryEngine {
                     return;
                 const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
                 const eventObjects = events.filter((evt) => isJsonObject(evt));
-                if (eventObjects.length > 0) {
-                    client._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq);
-                }
+                client._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq, Number.isSafeInteger(result.contiguous_seq)
+                    ? result.contiguous_seq
+                    : undefined);
                 const cursor = isJsonObject(result.cursor)
                     ? result.cursor
                     : null;
@@ -1710,6 +1787,7 @@ export class MessageDeliveryEngine {
                 }
                 const eventSeqs = [];
                 let hasDissolvedEvent = false;
+                let publishedEventCount = 0;
                 for (const evt of eventObjects) {
                     const eventSeq = Number(evt.event_seq ?? 0);
                     if (Number.isFinite(eventSeq) && eventSeq > 0)
@@ -1729,10 +1807,12 @@ export class MessageDeliveryEngine {
                             }
                         }
                         if (Number.isFinite(eventSeq) && eventSeq > 0 && !client._pushedSeqs.get(ns)?.has(eventSeq)) {
-                            this.enqueueOrderedMessage(ns, 'group.changed', eventSeq, evt);
+                            this.enqueueOrderedMessage(ns, 'group.changed', eventSeq, evt, 'pull');
+                            publishedEventCount += 1;
                         }
                     }
-                    filled += 1;
+                    if (et !== 'group.message_created')
+                        filled += 1;
                 }
                 const ackContig = client._seqTracker.getContiguousSeq(ns);
                 await this.drainOrderedMessages(ns);
@@ -1759,11 +1839,23 @@ export class MessageDeliveryEngine {
                         client._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`);
                     }
                 }
+                this.syncProgress(ns, {
+                    rawCount: eventObjects.length,
+                    pulledCount: publishedEventCount,
+                    remaining: result.remaining,
+                    hasMore: typeof result.has_more === 'boolean'
+                        ? Boolean(result.has_more) : undefined,
+                    currentSeq: ackContig,
+                    targetSeq: Math.max(Number(cursor?.latest_seq ?? 0), Number(result.latest_event_seq ?? 0)),
+                });
                 const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
-                if (singlePage && result.has_more === true && nextAfter > nextAfterSeq) {
+                const pageAdvanced = eventObjects.length > 0 && nextAfter > nextAfterSeq;
+                const needsMore = result.has_more === true
+                    || client._seqTracker.getMaxSeenSeq(ns) > nextAfter;
+                if (singlePage && pageAdvanced && needsMore) {
                     continuationAfterSeq = nextAfter;
                 }
-                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                if (!pageAdvanced || !needsMore)
                     break;
                 nextAfterSeq = nextAfter;
             }
@@ -1773,6 +1865,7 @@ export class MessageDeliveryEngine {
             client._clientLog.debug(`group event gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
+            failed = true;
             client._clientLog.warn(`group event gap fill failed: ${formatDeliveryError(exc)}`);
         }
         finally {
@@ -1789,6 +1882,8 @@ export class MessageDeliveryEngine {
             else if (!singlePage && filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
                 void this.fillGroupEventGap(groupId);
             }
+            if (!client._rpcPipeline)
+                this.syncStopped(failed ? 'aborted' : 'pull_drained');
         }
     }
     enqueueOnlineUnreadEventHint(data) {
@@ -1823,93 +1918,19 @@ export class MessageDeliveryEngine {
             this.enqueueOnlineUnreadEventHint(data);
             return;
         }
-        if (this.isSelfJoinGroupChanged(data)) {
-            const contig = client._seqTracker.getContiguousSeq(ns);
-            const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
-            if (contig === 0 && maxSeen === 0 && eventSeq > 1) {
-                client._clientLog.debug(`group.changed self-join baseline: group=${groupId}, event_seq=${eventSeq}, baseline=${eventSeq - 1}`);
-                client._seqTracker.forceContiguousSeq(ns, eventSeq - 1);
-            }
-        }
         const contigBefore = client._seqTracker.getContiguousSeq(ns);
         if (eventSeq <= contigBefore || client._pushedSeqs.get(ns)?.has(eventSeq)) {
             client._clientLog.debug(`group.changed skipped duplicate/stale: group=${groupId}, event_seq=${eventSeq}, contiguous=${contigBefore}`);
-            this.fireGroupEventAck(groupId, Math.min(eventSeq, contigBefore > 0 ? contigBefore : eventSeq), 'covered push');
             return;
         }
-        this.enqueueOrderedMessage(ns, 'group.changed', eventSeq, data);
-        needPull = client._seqTracker.onMessageSeq(ns, eventSeq);
-        const ackContig = client._seqTracker.getContiguousSeq(ns);
-        await this.drainOrderedMessages(ns);
-        if (ackContig > 0 && ackContig !== contigBefore) {
-            if (data.action !== 'dissolved')
-                this.persistSeq(ns);
-            client._transport.call('group.ack_events', {
-                group_id: groupId,
-                event_seq: ackContig,
-                device_id: client._deviceId,
-                slot_id: client._slotId,
-            }, undefined, undefined, true).catch((e) => {
-                client._clientLog.debug(`group event push auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`);
-            });
-        }
-        if (needPull && groupId && !data._from_gap_fill && client._sessionOptions?.background_sync !== false) {
+        client._seqTracker.updateMaxSeen(ns, eventSeq);
+        needPull = eventSeq > contigBefore;
+        if (needPull && !data._from_gap_fill && client._sessionOptions?.background_sync !== false) {
             this.fillGroupEventGap(groupId).catch((exc) => {
                 client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`);
             });
         }
     }
-    fireGroupEventAck(groupId, eventSeq, reason) {
-        const client = this.runtime.client;
-        const gid = String(groupId ?? '').trim();
-        if (!gid)
-            return;
-        const ns = `group_event:${gid}`;
-        const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, Number(eventSeq) || 0);
-        if (ackSeq <= 0)
-            return;
-        const params = {
-            group_id: gid,
-            event_seq: ackSeq,
-            device_id: client._deviceId,
-            slot_id: client._slotId,
-            _rpc_background: true,
-        };
-        try {
-            Promise.resolve(client.call('group.ack_events', params)).catch((e) => {
-                client._clientLog.debug(`group event ${reason} ack failed: group=${gid} ${formatDeliveryError(e)}`);
-            });
-        }
-        catch (e) {
-            client._clientLog.debug(`group event ${reason} ack failed: group=${gid} ${formatDeliveryError(e)}`);
-        }
-    }
-    fireGroupV2Ack(groupId, upToSeq, reason, groupAid = '') {
-        const client = this.runtime.client;
-        const gid = String(groupId ?? '').trim();
-        if (!gid)
-            return;
-        const ns = `group:${gid}`;
-        const ackSeq = this.clampAckSeq('group.v2.ack', 'up_to_seq', ns, Number(upToSeq) || 0);
-        if (ackSeq <= 0)
-            return;
-        const generation = this.inlineAckGeneration;
-        try {
-            Promise.resolve(client.call('group.v2.ack', {
-                group_id: gid,
-                ...(groupAid ? { group_aid: groupAid } : {}),
-                up_to_seq: ackSeq,
-                _rpc_background: true,
-            })).then((result) => {
-                this.onGroupV2AckResult(gid, result, ackSeq, generation);
-            }).catch((e) => {
-                client._clientLog.debug(`group.v2 ${reason} ack failed: group=${gid} ${formatDeliveryError(e)}`);
-            });
-        }
-        catch (e) {
-            client._clientLog.debug(`group.v2 ${reason} ack failed: group=${gid} ${formatDeliveryError(e)}`);
-        }
-    }
     isSelfJoinGroupChanged(data) {
         const action = String(data.action ?? '').trim();
         if (!['member_added', 'joined', 'join_approved', 'invite_code_used'].includes(action))
@@ -2206,15 +2227,17 @@ export class MessageDeliveryEngine {
         const state = this.syncState(ns);
         const needsForward = state.ack < state.tail - 1;
         const backgroundEnabled = client._sessionOptions?.background_sync !== false;
-        // Tail 期间到达的新 Push 可能只更新 maxSeen 而没有扩展 Tail 窗口。
+        // Tail 期间到达的新 Push 只记录在 pending Pull 上界，不写入 SeqTracker。
         const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
-        const tailMissedDuringPull = tailHead !== null && maxSeen > state.head;
+        const pendingUpper = Number(client._pendingP2pPullUpper?.get?.(ns) ?? 0);
+        const observedUpper = Math.max(maxSeen, pendingUpper);
+        const tailMissedDuringPull = tailHead !== null && observedUpper > state.head;
         const tailForward = tailHead !== null && (needsForward || tailMissedDuringPull);
         const backgroundWindowForward = (order.length === 1 && order[0] === 'forward' && !headForward)
             || (order.length === 1 && order[0] === 'tail' && tailHead === null && needsForward);
         const foregroundForward = headForward || tailForward;
         if (foregroundForward || backgroundEnabled && backgroundWindowForward) {
-            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? observedUpper : 0);
             const requiredPages = Math.max(1, Math.ceil(Math.max(0, forwardTarget - state.ack) / pageLimit));
             result = await run({
                 after_seq: state.ack,
@@ -2282,13 +2305,15 @@ export class MessageDeliveryEngine {
         const needsForward = state.ack < state.tail - 1;
         const backgroundEnabled = client._sessionOptions?.background_sync !== false;
         const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
-        const tailMissedDuringPull = tailHead !== null && maxSeen > state.head;
+        const pendingUpper = this.pendingPullUpper(ns);
+        const observedUpper = Math.max(maxSeen, pendingUpper);
+        const tailMissedDuringPull = tailHead !== null && observedUpper > state.head;
         const tailForward = tailHead !== null && (needsForward || tailMissedDuringPull);
         const backgroundWindowForward = (order.length === 1 && order[0] === 'forward' && !headForward)
             || (order.length === 1 && order[0] === 'tail' && tailHead === null && needsForward);
         const foregroundForward = headForward || tailForward;
         if (foregroundForward || backgroundEnabled && backgroundWindowForward) {
-            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? observedUpper : 0);
             const requiredPages = Math.max(1, Math.ceil(Math.max(0, forwardTarget - state.ack) / pageLimit));
             result = await run({
                 after_seq: state.ack,
@@ -2898,7 +2923,7 @@ export class MessageDeliveryEngine {
             this.enqueueOnlineUnreadP2pHint(pushData);
             return;
         }
-        const inlinePresent = Object.prototype.hasOwnProperty.call(pushData, 'inline_message');
+        const inlinePresent = hasNonEmptyInlineMessage(pushData.inline_message);
         const pushSeq = this.realtimeHeadSeq(rawPushSeq, inlinePresent);
         if (pushSeq === null) {
             if (inlinePresent) {
@@ -2929,7 +2954,8 @@ export class MessageDeliveryEngine {
         client._seqTracker.updateMaxSeen(ns, pushSeq);
         if (pushSeq <= before.ack && before.ack >= before.tail - 1) {
             client._clientLog.debug(`V2 P2P duplicate push ignored: seq=${pushSeq} A/T/H=${JSON.stringify(before)}`);
-            this.retryPendingP2PInlineAck(ns, pushSeq, 'covered inline push');
+            if (inlinePresent)
+                this.retryPendingP2PInlineAck(ns, pushSeq, 'covered inline push');
             return;
         }
         const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
@@ -3002,7 +3028,7 @@ export class MessageDeliveryEngine {
         client._logMessageDebug('server-push', '_raw.group.v2.message_created', 'group.message_created', d);
         const groupId = typeof d.group_id === 'string' ? d.group_id.trim() : '';
         const rawSeq = d.seq;
-        const inlinePresent = Object.prototype.hasOwnProperty.call(d, 'inline_message');
+        const inlinePresent = hasNonEmptyInlineMessage(d.inline_message);
         const seq = this.realtimeHeadSeq(rawSeq, inlinePresent);
         if (!groupId) {
             client._clientLog.debug(`_onRawGroupV2MessageCreated skipped: group=${groupId || '<empty>'}, seq=${String(d.seq ?? '')}`);
@@ -3047,12 +3073,9 @@ export class MessageDeliveryEngine {
         if (seq <= before.ack && before.ack >= before.tail - 1) {
             client._clientLog.debug(`V2 group duplicate push ignored: group=${groupId} seq=${seq} A/T/H=${JSON.stringify(before)}`);
             const pending = this.pendingGroupInlineAcks?.get(ns);
-            if (pending?.seq === seq) {
+            if (inlinePresent && pending?.seq === seq) {
                 this.retryPendingGroupInlineAck(ns, seq, 'covered inline push');
             }
-            else if (!inlinePresent) {
-                this.fireGroupV2Ack(groupId, seq, 'covered push');
-            }
             return;
         }
         const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
@@ -3602,44 +3625,18 @@ export class MessageDeliveryEngine {
         }
         return true;
     }
-    async publishOrderedGroupRecall(ns, seq, message) {
-        const client = this.runtime.client;
-        this.ensurePullOperationCurrent();
-        const seqNum = Number(seq);
-        if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
-            await this.publishGroupRecallTombstone(ns.replace(/^group:/, ''), seq, message);
-            this.ensurePullOperationCurrent();
-            return true;
-        }
-        // 撤回 tombstone 也占 seq：推进 contiguous 并标记已发布，确保 ack 正常推进、不留空洞。
-        if (client._pushedSeqs.get(ns)?.has(seqNum)) {
-            await this.publishGroupRecallTombstone(ns.replace(/^group:/, ''), seq, message);
-            return false;
-        }
-        client._seqTracker.onMessageSeq(ns, seqNum);
-        await this.publishGroupRecallTombstone(ns.replace(/^group:/, ''), seq, message);
-        this.ensurePullOperationCurrent();
-        this.markPublishedSeq(ns, seqNum);
-        client._markOrderedSeqDelivered?.(ns, seqNum);
-        await this.drainOrderedMessages(ns);
-        if (!client._pendingOrderedMsgs.get(ns)) {
-            this.ensurePullOperationCurrent();
-            await this.saveSeqTrackerState();
-        }
-        return true;
-    }
-    async publishPulledMessage(event, ns, seq, payload, persist = true) {
+    async publishPulledMessage(event, ns, seq, payload, persist = true, source = 'pull') {
         const client = this.runtime.client;
         this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
             client._clientLog.debug(`publish pulled direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
             if (event === 'message.recalled') {
-                const published = await this.publishMessageRecallTombstone(seq, payload);
+                const published = await this.publishMessageRecallTombstone(seq, payload, source);
                 this.ensurePullOperationCurrent();
                 return published;
             }
-            const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
+            const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source));
             if (isPromiseLike(published))
                 await published;
             this.ensurePullOperationCurrent();
@@ -3653,27 +3650,27 @@ export class MessageDeliveryEngine {
                 client._pendingOrderedMsgs.delete(ns);
             return false;
         }
-        await this.drainOrderedMessages(ns, seqNum, true, persist, 'pull');
+        await this.drainOrderedMessages(ns, seqNum, true, persist, source);
         this.ensurePullOperationCurrent();
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             client._pendingOrderedMsgs.delete(ns);
         if (event === 'message.recalled') {
-            const recallPublished = await this.publishMessageRecallTombstone(seqNum, payload);
+            const recallPublished = await this.publishMessageRecallTombstone(seqNum, payload, source);
             this.ensurePullOperationCurrent();
             this.markPublishedSeq(ns, seqNum);
             client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
-            await this.drainOrderedMessages(ns, undefined, true, persist, 'pull');
+            await this.drainOrderedMessages(ns, undefined, true, persist, source);
             this.ensurePullOperationCurrent();
             return recallPublished;
         }
-        const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
+        const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, source));
         if (isPromiseLike(published))
             await published;
         this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
-        await this.drainOrderedMessages(ns, undefined, true, persist, 'pull');
+        await this.drainOrderedMessages(ns, undefined, true, persist, source);
         this.ensurePullOperationCurrent();
         return true;
     }