@agentunion/fastaun-browser 0.5.6 → 0.5.8

package/dist/client/rpc-pipeline.js

@@ -1,5 +1,5 @@
 import { normalizeSlotId, slotIsolationKey } from '../config.js';
-import { ClientSignatureError, ConnectionError, PermissionError, ValidationError } from '../errors.js';
+import { ClientSignatureError, ConnectionError, PermissionError, TimeoutError, ValidationError } from '../errors.js';
 import { validateAIDFormat, validateGroupIDFormat } from '../validators.js';
 import { p1363ToDer, pemToArrayBuffer, uint8ToBase64 } from '../crypto.js';
 import { ConnectionState, isJsonObject, } from '../types.js';
@@ -119,9 +119,10 @@ async function signingCertFingerprint(certPem) {
     return await cached;
 }
 const PULL_GATE_STALE_MS = 30000;
+const PULL_GATE_OPERATION_TIMEOUT_MS = 3000;
 const NON_IDEMPOTENT_TIMEOUT = 35;
 const NON_IDEMPOTENT_METHODS = new Set([
-    'message.send', 'group.send', 'group.create', 'group.invite',
+    'message.send', 'mail.send', 'group.send', 'group.create', 'group.invite',
     'group.kick', 'group.remove_member', 'group.leave', 'group.dissolve',
     'group.set_settings',
     'group.update_announcement', 'group.update_rules',
@@ -168,7 +169,7 @@ function isTransientV2PullFallbackError(error) {
 export class RpcPipeline {
     runtime;
     pullGateStates = new Map();
-    bypassedRealtimePulls = new Map();
+    inlineRealtimeScopes = new Set();
     constructor(runtime) {
         this.runtime = runtime;
     }
@@ -198,6 +199,8 @@ export class RpcPipeline {
         };
         const skipSendResultEnvelope = Boolean(p._skip_send_result_envelope);
         delete p._skip_send_result_envelope;
+        const deferGroupReadyPostprocess = Boolean(p._defer_group_ready_postprocess);
+        delete p._defer_group_ready_postprocess;
         if (method === 'message.send') {
             const encrypt = p.encrypt !== undefined ? p.encrypt : true;
             delete p.encrypt;
@@ -249,15 +252,11 @@ export class RpcPipeline {
         }
         const pullGateKey = this.pullGateKeyForCall(method, p);
         if (pullGateKey) {
-            if (this.isPullResponseProcessing(pullGateKey)) {
-                client._clientLog.debug(`pull skipped while processing pull response: method=${method} key=${pullGateKey}`);
-                return this.emptyPullResultForCall(method);
-            }
-            return await this.runPullSerialized(pullGateKey, async () => await this.callImplInner(method, p, skipSendResultEnvelope), this.pullGateBackgroundForCall(method, p));
+            return await this.runPullSerialized(pullGateKey, async () => await this.callImplInner(method, p, skipSendResultEnvelope, deferGroupReadyPostprocess), rpcBackground && this.pullGateBackgroundForCall(method, p));
         }
-        return await runWithRpcPriority(() => this.callImplInner(method, p, skipSendResultEnvelope));
+        return await runWithRpcPriority(() => this.callImplInner(method, p, skipSendResultEnvelope, deferGroupReadyPostprocess));
     }
-    async callImplInner(method, p, skipSendResultEnvelope = false) {
+    async callImplInner(method, p, skipSendResultEnvelope = false, deferGroupReadyPostprocess = false) {
         const client = this.runtime.client;
         if (method === 'message.v2.pull' || (method === 'message.pull' && hasMatchingV2Session(client))) {
             try {
@@ -265,7 +264,10 @@ export class RpcPipeline {
                 client._clientLog.debug(`call route: ${method} -> V2 pull`);
                 if (p.window_mode === 'tail')
                     return await client._v2E2EE.pullV2TailInternal(p);
-                const messages = await client._pullV2(Number(p.after_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, { force: p.force === true });
+                const messages = await client._pullV2(Number(p.after_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, {
+                    gateLocked: true,
+                    force: p.force === true,
+                });
                 return { messages };
             }
             catch (exc) {
@@ -290,9 +292,11 @@ export class RpcPipeline {
             if (p.window_mode === 'tail')
                 return await client._v2E2EE.pullGroupV2TailInternal(p);
             const hasExplicitAfterSeq = 'after_seq' in p || 'after_message_seq' in p;
-            const cursorParams = client._explicitGroupCursorParams(p);
-            const ownsCursor = Object.keys(cursorParams).length === 0 || client._groupCursorTargetsCurrentInstance(cursorParams);
-            const pullOpts = {};
+            const cursorParams = this.explicitGroupCursorParams(p);
+            const ownsCursor = Object.keys(cursorParams).length === 0 || this.groupCursorTargetsCurrentInstance(cursorParams);
+            const pullOpts = {
+                gateLocked: true,
+            };
             if (hasExplicitAfterSeq)
                 pullOpts.explicitAfterSeq = true;
             if (p.force === true)
@@ -317,8 +321,8 @@ export class RpcPipeline {
         if ((method === 'group.v2.ack' || method === 'group.ack_messages') && p.group_id && (method === 'group.v2.ack' || hasMatchingV2Session(client))) {
             await client._ensureV2SessionReady('group.ack_messages');
             client._clientLog.debug(`call route: ${method} -> V2 ack`);
-            const cursorParams = client._explicitGroupCursorParams(p);
-            const ownsCursor = Object.keys(cursorParams).length === 0 || client._groupCursorTargetsCurrentInstance(cursorParams);
+            const cursorParams = this.explicitGroupCursorParams(p);
+            const ownsCursor = Object.keys(cursorParams).length === 0 || this.groupCursorTargetsCurrentInstance(cursorParams);
             if (!ownsCursor) {
                 return await client._rawGroupAckMessages(p);
             }
@@ -327,11 +331,15 @@ export class RpcPipeline {
         await this.applyClientSignature(method, p);
         const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT : undefined;
         const rpcBackground = client._backgroundRpcDepth > 0;
-        let result = callTimeout
-            ? await client._transport.call(method, p, callTimeout, undefined, rpcBackground)
-            : await client._transport.call(method, p, undefined, undefined, rpcBackground);
+        const invokeTransport = () => {
+            const request = callTimeout
+                ? client._transport.call(method, p, callTimeout, undefined, rpcBackground)
+                : client._transport.call(method, p, undefined, undefined, rpcBackground);
+            return this.bindActivePullCancellation(method, p, request);
+        };
+        let result = await this.transportCallWithIdentityRecovery(invokeTransport, method, p);
         const sendResultModeSource = result;
-        result = await this.postprocessResult(method, p, result);
+        result = await this.postprocessResult(method, p, result, { skipGroupState: deferGroupReadyPostprocess });
         if (!skipSendResultEnvelope) {
             result = client._delivery.attachSendResultEnvelope(method, p, result, Boolean(p.encrypted), sendResultModeSource);
         }
@@ -561,23 +569,58 @@ export class RpcPipeline {
         return true;
     }
     pullGateName(key) {
-        if (key.startsWith('p2p:'))
-            return 'p2p_message';
-        if (key.startsWith('group:'))
-            return 'group_message';
-        if (key.startsWith('group_event:'))
-            return 'group_event';
-        return `other:${key}`;
+        void key;
+        return 'pull';
     }
     pullGateState(key) {
         const name = this.pullGateName(key);
         let state = this.pullGateStates.get(name);
         if (!state) {
-            state = { active: null, foreground: [], background: [], byKey: new Map() };
+            state = { active: null, foreground: [], background: [], byKey: new Map(), lifecycle: new Map(), watchdog: null };
             this.pullGateStates.set(name, state);
+            this.startPullGateWatchdog(state, name);
         }
         return state;
     }
+    pullGateOperationTimeoutMs() {
+        const client = this.runtime.client;
+        const configured = Number(client._PULL_GATE_OPERATION_TIMEOUT_MS
+            ?? client._PULL_GATE_TIMEOUT_MS
+            ?? client._PULL_GATE_QUEUE_TIMEOUT_MS);
+        return Number.isFinite(configured) && configured > 0 ? configured : PULL_GATE_OPERATION_TIMEOUT_MS;
+    }
+    startPullGateWatchdog(state, name) {
+        if (state.watchdog)
+            return;
+        const interval = Math.min(50, Math.max(1, Math.floor(this.pullGateOperationTimeoutMs() / 4)));
+        const timer = setInterval(() => this.checkPullGate(state, name), interval);
+        state.watchdog = timer;
+        timer.unref?.();
+    }
+    checkPullGate(state, name) {
+        const active = state.active;
+        if (!active) {
+            this.drainPullGate(state);
+            return;
+        }
+        if (!active.pullingStartedAt || Date.now() - active.pullingStartedAt < this.pullGateOperationTimeoutMs())
+            return;
+        if (active.timedOut)
+            return;
+        active.timedOut = true;
+        active.cancel?.();
+        const err = new TimeoutError(`pull gate timeout: ${active.namespace}`, { retryable: true });
+        this.runtime.client._clientLog?.warn(`pull gate watchdog timeout: gate=${name} key=${active.key}`);
+        state.lifecycle.set(active.namespace, 'idle');
+        if (state.active === active)
+            state.active = null;
+        if (state.byKey.get(active.key) === active)
+            state.byKey.delete(active.key);
+        active.resolve = () => { };
+        active.reject(err);
+        this.drainPullGate(state);
+        this.runtime.client._delivery?.onPullGateIdle?.(active.namespace);
+    }
     realtimePullNamespace(key) {
         for (const marker of ['|tail|', '|forward|']) {
             const index = key.indexOf(marker);
@@ -590,6 +633,22 @@ export class RpcPipeline {
         const index = key.indexOf('|');
         return index < 0 ? key : key.slice(0, index);
     }
+    bindActivePullCancellation(method, params, request) {
+        const cancel = request.cancel;
+        const key = this.pullGateKeyForCall(method, params);
+        if (typeof cancel !== 'function' || !key)
+            return request;
+        const state = this.pullGateStates.get(this.pullGateName(key));
+        const active = state?.active;
+        if (!active || active.namespace !== this.pullScopeKey(key) || active.timedOut)
+            return request;
+        const boundCancel = () => cancel.call(request);
+        active.cancel = boundCancel;
+        return request.finally(() => {
+            if (active.cancel === boundCancel)
+                active.cancel = null;
+        });
+    }
     isPullResponseProcessing(key) {
         const responseKeys = this.runtime.client._pullResponseKeys;
         return Boolean(key) && (responseKeys?.get(this.pullScopeKey(key)) ?? 0) > 0;
@@ -599,33 +658,12 @@ export class RpcPipeline {
             return { events: [], count: 0 };
         return { messages: [], count: 0 };
     }
-    trackBypassedRealtimePull(key, delta) {
-        const ns = this.realtimePullNamespace(key);
-        if (!ns)
-            return;
-        const next = Math.max(0, (this.bypassedRealtimePulls.get(ns) ?? 0) + delta);
-        if (next === 0)
-            this.bypassedRealtimePulls.delete(ns);
-        else
-            this.bypassedRealtimePulls.set(ns, next);
-    }
-    async executeBypassedPull(key, operation, background) {
-        this.trackBypassedRealtimePull(key, 1);
-        try {
-            return await this.executePullOperation(operation, background);
-        }
-        finally {
-            this.trackBypassedRealtimePull(key, -1);
-        }
-    }
     hasPendingRealtimePull(ns) {
         const normalized = String(ns ?? '').trim();
         if (!normalized || (!normalized.startsWith('p2p:') && !normalized.startsWith('group:')))
             return false;
         if (this.isPullResponseProcessing(normalized))
             return true;
-        if ((this.bypassedRealtimePulls.get(normalized) ?? 0) > 0)
-            return true;
         const state = this.pullGateStates.get(this.pullGateName(normalized));
         if (!state)
             return false;
@@ -638,6 +676,36 @@ export class RpcPipeline {
             || state.foreground.some(matches)
             || state.background.some(matches);
     }
+    hasPullActivity(namespace, includePending = true) {
+        const ns = String(namespace ?? '').trim();
+        if ((!ns.startsWith('p2p:') && !ns.startsWith('group:'))
+            || this.inlineRealtimeScopes.has(ns))
+            return true;
+        const client = this.runtime.client;
+        if ((client._pullResponseKeys?.get?.(ns) ?? 0) > 0)
+            return true;
+        const pendingP2p = client._pendingP2pPullUpper;
+        const pendingGroup = client._pendingGroupPullUpper;
+        if (includePending && ((pendingP2p?.get(ns) ?? 0) > 0 || (pendingGroup?.get(ns) ?? 0) > 0
+            || client._delivery?.hasPendingPull?.(ns)))
+            return true;
+        for (const marker of client._gapFillDone ?? []) {
+            const value = String(marker ?? '').trim();
+            if (ns.startsWith('p2p:') && (value.startsWith('p2p_pull:') || value.startsWith('p2p_pull_retry:')))
+                return true;
+            if (ns.startsWith('group:') && value.startsWith(`group_pull:${ns}`))
+                return true;
+        }
+        for (const [key, gate] of client._pullGates?.entries?.() ?? []) {
+            if (gate?.inflight && this.pullScopeKey(key) === ns)
+                return true;
+        }
+        const state = this.pullGateStates.get(this.pullGateName(ns));
+        if (!state)
+            return false;
+        const matches = (job) => job !== null && job.namespace === ns;
+        return matches(state.active) || state.foreground.some(matches) || state.background.some(matches);
+    }
     async tryRunInlineRealtime(ns, seq, operation) {
         const normalized = String(ns ?? '').trim();
         if ((!normalized.startsWith('p2p:') && !normalized.startsWith('group:'))
@@ -645,8 +713,10 @@ export class RpcPipeline {
             return { acquired: false };
         }
         const client = this.runtime.client;
-        if (this.isPullResponseProcessing(normalized)
-            || (this.bypassedRealtimePulls.get(normalized) ?? 0) > 0) {
+        if (this.hasPullActivity(normalized)) {
+            return { acquired: false };
+        }
+        if (this.isPullResponseProcessing(normalized)) {
             return { acquired: false };
         }
         for (const [key, gate] of client._pullGates?.entries?.() ?? []) {
@@ -660,28 +730,40 @@ export class RpcPipeline {
         }
         const guard = {
             key,
+            namespace: normalized,
             background: false,
+            running: true,
+            suspended: false,
             inline: true,
             operation,
             promise: Promise.resolve(undefined),
             resolve: () => { },
             reject: () => { },
             timer: null,
+            resume: null,
+            resumeResolve: null,
+            pullingStartedAt: 0,
+            timedOut: false,
+            cancel: null,
         };
-        state.active = guard;
+        this.inlineRealtimeScopes.add(normalized);
         try {
             return { acquired: true, value: await operation() };
         }
         finally {
+            this.inlineRealtimeScopes.delete(normalized);
             if (state.active === guard)
                 state.active = null;
             this.drainPullGate(state);
+            this.runtime.client._delivery?.onPullGateIdle?.(normalized);
             this.armQueuedPullTimers(state);
         }
     }
     tryAcquirePullGate(key) {
         if (!key)
             return 0;
+        if (this.inlineRealtimeScopes.has(this.pullScopeKey(key)))
+            return null;
         const serialized = this.pullGateStates.get(this.pullGateName(key));
         if (serialized?.active?.inline === true)
             return null;
@@ -710,30 +792,41 @@ export class RpcPipeline {
         gate.startedAt = 0;
     }
     async runPullSerialized(key, operation, background = false) {
-        if (key && this.isPullResponseProcessing(key)) {
-            this.runtime.client._clientLog.debug(`pull skipped while processing pull response: key=${key}`);
-            return [];
-        }
         if (!key)
             return await this.executePullOperation(operation, background);
         const state = this.pullGateState(key);
-        const timeoutMs = Math.max(0, Number(this.runtime.client._PULL_GATE_QUEUE_TIMEOUT_MS ?? 3_000) || 0);
-        const existing = state.byKey.get(key);
+        const namespace = this.pullScopeKey(key);
+        const active = state.active?.namespace === namespace ? state.active : null;
+        const queuedForeground = state.foreground.find((job) => job.namespace === namespace);
+        const queuedBackground = state.background.find((job) => job.namespace === namespace);
+        const existing = background
+            ? (active ?? queuedForeground ?? queuedBackground)
+            : (queuedForeground ?? (active && !active.background ? active : null) ?? queuedBackground);
         if (existing) {
-            if (state.active?.inline === true)
-                return await existing.promise;
-            return await this.waitForCoalesced(existing.promise, timeoutMs, operation, background, key);
+            if (!background && existing.background && existing !== state.active) {
+                const index = state.background.indexOf(existing);
+                if (index >= 0)
+                    state.background.splice(index, 1);
+                existing.background = false;
+                state.foreground.push(existing);
+            }
+            return await existing.promise;
         }
         let resolve;
         let reject;
         const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
-        const job = { key, background, operation, promise, resolve, reject, timer: null };
+        void promise.catch(() => { });
+        const job = {
+            key, namespace, background, running: false, suspended: false, operation, promise, resolve, reject, timer: null,
+            resume: null, resumeResolve: null,
+            pullingStartedAt: 0,
+            timedOut: false,
+            cancel: null,
+        };
         (background ? state.background : state.foreground).push(job);
         state.byKey.set(key, job);
         this.drainPullGate(state);
-        if (state.active !== job && state.active?.inline !== true) {
-            job.timer = setTimeout(() => this.bypassQueuedPull(state, job), timeoutMs);
-        }
+        this.checkPullGate(state, this.pullGateName(key));
         return await promise;
     }
     async executePullOperation(operation, background) {
@@ -741,65 +834,86 @@ export class RpcPipeline {
             return await this.runtime.client._withBackgroundRpc(operation);
         return await operation();
     }
-    waitForCoalesced(shared, timeoutMs, operation, background, key) {
-        return new Promise((resolve, reject) => {
-            let settled = false;
-            const timer = setTimeout(() => {
-                if (settled)
-                    return;
-                settled = true;
-                this.runtime.client._clientLog.warn(`pull gate coalesced wait timeout, bypass: gate=${this.pullGateName(key)} key=${key}`);
-                void this.executeBypassedPull(key, operation, background).then(resolve, reject);
-            }, timeoutMs);
-            shared.then((value) => { if (!settled) {
-                settled = true;
-                clearTimeout(timer);
-                resolve(value);
-            } }, (error) => { if (!settled) {
-                settled = true;
-                clearTimeout(timer);
-                reject(error);
-            } });
-        });
-    }
-    bypassQueuedPull(state, job) {
-        if (state.active === job)
+    async yieldPullGate(key, nextKey, background) {
+        if (!key)
             return;
-        const queue = job.background ? state.background : state.foreground;
-        const index = queue.indexOf(job);
-        if (index < 0)
+        const state = this.pullGateState(key);
+        const namespace = this.pullScopeKey(key);
+        const job = state.active?.namespace === namespace
+            ? state.active
+            : [...state.foreground, ...state.background].find((candidate) => candidate.namespace === namespace);
+        if (!job || state.active !== job)
             return;
-        queue.splice(index, 1);
+        const replacementKey = String(nextKey || key);
         if (state.byKey.get(job.key) === job)
             state.byKey.delete(job.key);
-        job.timer = null;
-        this.runtime.client._clientLog.warn(`pull gate queue timeout, bypass: gate=${this.pullGateName(job.key)} key=${job.key}`);
-        void this.executeBypassedPull(job.key, job.operation, job.background).then(job.resolve, job.reject);
+        job.key = replacementKey;
+        job.namespace = this.pullScopeKey(replacementKey);
+        if (background !== undefined)
+            job.background = background;
+        state.byKey.set(job.key, job);
+        state.lifecycle.set(namespace, 'pulled');
+        job.suspended = true;
+        job.resume = new Promise((resolve) => { job.resumeResolve = resolve; });
+        state.active = null;
+        (job.background ? state.background : state.foreground).push(job);
+        this.drainPullGate(state);
+        if (job.resume)
+            await job.resume;
+    }
+    getPullLifecycle(namespace) {
+        const ns = this.pullScopeKey(namespace);
+        if (!ns)
+            return 'idle';
+        return this.pullGateStates.get(this.pullGateName(ns))?.lifecycle.get(ns) ?? 'idle';
+    }
+    setPullLifecycle(namespace, lifecycle) {
+        const ns = this.pullScopeKey(namespace);
+        if (!ns)
+            return;
+        const state = this.pullGateStates.get(this.pullGateName(ns));
+        if (!state || state.active?.namespace !== ns)
+            return;
+        state.lifecycle.set(ns, lifecycle);
     }
     drainPullGate(state) {
         if (state.active)
             return;
-        const job = state.foreground.shift() ?? state.background.shift();
+        const takeRunnable = (queue) => {
+            const index = queue.findIndex((candidate) => !this.inlineRealtimeScopes.has(candidate.namespace));
+            return index >= 0 ? queue.splice(index, 1)[0] : undefined;
+        };
+        const job = takeRunnable(state.foreground) ?? takeRunnable(state.background);
         if (!job)
             return;
         state.active = job;
         if (job.timer)
             clearTimeout(job.timer);
+        job.pullingStartedAt = Date.now();
+        job.timedOut = false;
+        state.lifecycle.set(job.namespace, 'pulling');
+        const resumeResolve = job.resumeResolve;
+        job.resume = null;
+        job.resumeResolve = null;
+        if (job.suspended) {
+            job.suspended = false;
+            resumeResolve?.();
+            return;
+        }
+        job.running = true;
         void this.executePullOperation(job.operation, job.background).then(job.resolve, job.reject).finally(() => {
+            if (job.timedOut)
+                return;
+            state.lifecycle.set(job.namespace, 'idle');
             if (state.active === job)
                 state.active = null;
             if (state.byKey.get(job.key) === job)
                 state.byKey.delete(job.key);
             this.drainPullGate(state);
+            this.runtime.client._delivery?.onPullGateIdle?.(job.namespace);
         });
     }
-    armQueuedPullTimers(state) {
-        const timeoutMs = Math.max(0, Number(this.runtime.client._PULL_GATE_QUEUE_TIMEOUT_MS ?? 3_000) || 0);
-        for (const job of [...state.foreground, ...state.background]) {
-            if (!job.timer)
-                job.timer = setTimeout(() => this.bypassQueuedPull(state, job), timeoutMs);
-        }
-    }
+    armQueuedPullTimers(_state) { }
     async rawCall(method, params, options) {
         const client = this.runtime.client;
         const payload = { ...(params ?? {}) };
@@ -810,18 +924,32 @@ export class RpcPipeline {
             await this.applyClientSignature(method, payload);
         }
         const timeout = options?.timeout;
-        if (rpcBackground) {
-            return await client._transport.call(method, payload, timeout, options?.trace, true);
-        }
-        if (options?.trace !== undefined) {
-            return await client._transport.call(method, payload, timeout, options.trace);
+        const invokeTransport = () => {
+            let request;
+            if (rpcBackground)
+                request = client._transport.call(method, payload, timeout, options?.trace, true);
+            else if (options?.trace !== undefined)
+                request = client._transport.call(method, payload, timeout, options.trace);
+            else if (timeout !== undefined)
+                request = client._transport.call(method, payload, timeout);
+            else
+                request = client._transport.call(method, payload);
+            return this.bindActivePullCancellation(method, payload, request);
+        };
+        return await this.transportCallWithIdentityRecovery(invokeTransport, method, payload);
+    }
+    async transportCallWithIdentityRecovery(operation, method, params) {
+        try {
+            return await operation();
         }
-        if (timeout !== undefined) {
-            return await client._transport.call(method, payload, timeout);
+        catch (err) {
+            const recover = this.runtime.client._recoverIdentityAdmission;
+            if (typeof recover !== 'function' || !await recover.call(this.runtime.client, err, method, params))
+                throw err;
+            return await operation();
         }
-        return await client._transport.call(method, payload);
     }
-    async postprocessResult(method, params, result) {
+    async postprocessResult(method, params, result, options = {}) {
         const client = this.runtime.client;
         let next = result;
         if ((method === 'group.send' || method === 'group.v2.send') && isJsonObject(next)) {
@@ -839,12 +967,40 @@ export class RpcPipeline {
             next = await client._decryptMessageThoughts(next);
         }
         if (method === 'message.pull' && isJsonObject(next)) {
-            this.postprocessMessagePull(params, next);
+            const isTail = String(next.window_mode ?? params.window_mode ?? '').trim().toLowerCase() === 'tail';
+            if (!isTail && client._aid && client._seqTracker) {
+                const ns = `p2p:${client._aid}`;
+                const afterSeq = Math.max(0, Number(params.after_seq ?? 0) || 0);
+                await client._delivery.commitPlainForwardPage(ns, afterSeq, 'message.pull', next);
+            }
+            else {
+                this.postprocessMessagePull(params, next);
+            }
         }
         if (method === 'group.pull' && isJsonObject(next)) {
-            this.postprocessGroupPull(params, next);
+            if (Array.isArray(next.messages)) {
+                next.messages = next.messages.map((message) => normalizeGroupMentionMode(message));
+            }
+            const gid = String(params.group_id ?? params.group_aid ?? '').trim();
+            const explicitCursorParams = this.explicitGroupCursorParams(params);
+            const ownsCursor = Object.keys(explicitCursorParams).length === 0
+                || this.groupCursorTargetsCurrentInstance(explicitCursorParams);
+            const isTail = String(next.window_mode ?? params.window_mode ?? '').trim().toLowerCase() === 'tail';
+            if (!ownsCursor) {
+                client._clientLog.debug(`group.pull external cursor skips local Forward commit: group=${gid}`);
+            }
+            else if (!isTail && gid && client._seqTracker) {
+                const ns = `group:${gid}`;
+                const afterSeq = Math.max(0, Number(params.after_message_seq ?? params.after_seq ?? 0) || 0);
+                await client._delivery.commitPlainForwardPage(ns, afterSeq, 'group.pull', next, gid);
+            }
+            else {
+                this.postprocessGroupPull(params, next);
+            }
+        }
+        if (!options.skipGroupState) {
+            next = await client._groupState.postprocessResult(method, params, next);
         }
-        next = await client._groupState.postprocessResult(method, params, next);
         return next;
     }
     _sleep(ms) {
@@ -960,6 +1116,19 @@ export class RpcPipeline {
         }
         return cursorParams;
     }
+    explicitGroupCursorParams(params) {
+        const value = params._group_cursor_params;
+        if (!isJsonObject(value))
+            return {};
+        return { ...value };
+    }
+    groupCursorTargetsCurrentInstance(params) {
+        const client = this.runtime.client;
+        const deviceId = String(params.device_id ?? '').trim();
+        const slotId = String(params.slot_id ?? '').trim();
+        return (!deviceId || deviceId === (client._deviceId ?? ''))
+            && (!slotId || slotId === (client._slotId ?? ''));
+    }
     validateMessageRecipient(toAid) {
         if (isGroupServiceAid(toAid)) {
             throw new ValidationError('message.send receiver cannot be group.{issuer}; use group.send instead');