@agentunion/fastaun 0.5.19 → 0.5.21

package/dist/client/rpc-pipeline.d.ts

@@ -13,6 +13,8 @@ export declare class RpcPipeline {
     private pullDrainedCheckQueued;
     constructor(runtime: ClientRuntime);
     call(method: string, params?: RpcParams): Promise<RpcResult>;
+    private _callWithSent;
+    private _call;
     preflight(method: string, params?: RpcParams): RpcPreflightResult;
     mergeInstanceProtectedHeaders(method: string, params: RpcParams): void;
     normalizeOutboundMessagePayload(params: RpcParams, method?: string): void;
@@ -43,7 +45,8 @@ export declare class RpcPipeline {
     isPullNamespaceCurrent(namespace: string): boolean;
     invalidatePulls(): Promise<void>;
     private pullInvalidationInProgress;
-    runPullSerialized<T>(key: string, operation: () => Promise<T> | T, background?: boolean): Promise<T>;
+    runPullNamespaceSerialized<T>(key: string, operation: () => Promise<T> | T, background?: boolean): Promise<T>;
+    runPullSerialized<T>(key: string, operation: () => Promise<T> | T, background?: boolean, namespaceOnly?: boolean): Promise<T>;
     private executePullOperation;
     private throwIfPullInvalidated;
     yieldPullGate(key: string, nextKey?: string, background?: boolean): Promise<void>;
@@ -61,6 +64,7 @@ export declare class RpcPipeline {
         background?: boolean;
         pullGateKey?: string;
     }): Promise<unknown>;
+    private observeBackgroundPullResponse;
     private transportCallWithIdentityRecovery;
     postprocessResult(method: string, params: RpcParams, result: unknown, options?: {
         skipGroupState?: boolean;

package/dist/client/rpc-pipeline.js

@@ -1,5 +1,5 @@
 import * as crypto from 'node:crypto';
-import { normalizeSlotId, slotIsolationKey } from '../config.js';
+import { _INTERNAL_MESSAGE_FLOW_LIMITS, normalizeSlotId, slotIsolationKey } from '../config.js';
 import { certTimeError } from '../cert-utils.js';
 import { orgRequestParams, validateOrgRequestJSON } from '../org-protocol.js';
 import { canonicalJson as canonicalClientRequest } from '../v2/crypto/canonical.js';
@@ -166,7 +166,14 @@ export class RpcPipeline {
         this.runtime = runtime;
     }
     async call(method, params) {
+        return this._call(method, params);
+    }
+    async _callWithSent(method, params, onSent) {
+        return this._call(method, params, onSent);
+    }
+    async _call(method, params, onSent) {
         const client = this.runtime.client;
+        const generation = client._delivery?.captureInlineAckGeneration?.();
         const tStart = Date.now();
         const requestedAckSeq = method === 'message.ack' || method === 'message.v2.ack'
             ? Number(params?.seq
@@ -192,6 +199,23 @@ export class RpcPipeline {
             const deferGroupReadyPostprocess = Boolean(p._defer_group_ready_postprocess);
             delete p._defer_group_ready_postprocess;
             const pullGateKey = this.pullGateKeyForCall(method, p);
+            if (client._p2pPeerPullEnabled && method === 'message.peers')
+                return await client._delivery.peers(p, rpcBackground);
+            if (client._p2pPeerPullEnabled && (method === 'message.pull' || method === 'message.v2.pull')) {
+                await client._ensureV2SessionReady('message.pull');
+                return await client._delivery.pullPeers(p, rpcBackground);
+            }
+            if (client._p2pPeerPullEnabled && method === 'message.history') {
+                await client._ensureV2SessionReady('message.history');
+                const key = this.pullGateKeyForCall(method, p);
+                return await this.runPullNamespaceSerialized(key, () => client._v2E2EE.peerHistoryV2(p), rpcBackground);
+            }
+            if (client._p2pPeerPullEnabled && (method === 'message.ack' || method === 'message.v2.ack')) {
+                const sender = String(p.sender_aid ?? '').trim();
+                if (!sender)
+                    throw new ValidationError('peer ACK requires sender_aid');
+                return await client._v2E2EE.ackPeerV2(sender, requestedAckSeq || undefined, Array.isArray(p.volatile_cursors) ? p.volatile_cursors : [], Array.isArray(p.volatile_ids) ? p.volatile_ids : []);
+            }
             const runWithPullResponseScope = async (operation) => {
                 const scope = pullGateNamespace || (pullGateKey ? this.pullScopeKey(pullGateKey) : '');
                 const wrapper = client._withPullResponseProcessing;
@@ -205,9 +229,13 @@ export class RpcPipeline {
                 lockedParams._pull_gate_namespace = this.pullScopeKey(pullGateKey);
                 if (pullBackground)
                     lockedParams._rpc_background = true;
+                else
+                    lockedParams._rpc_foreground = true;
                 if (skipSendResultEnvelope)
                     lockedParams._skip_send_result_envelope = true;
-                return await this.runPullSerialized(pullGateKey, async () => this.call(method, lockedParams), pullBackground);
+                const run = ['group.pull', 'group.v2.pull', 'group.history'].includes(method)
+                    ? this.runPullNamespaceSerialized.bind(this) : this.runPullSerialized.bind(this);
+                return await run(pullGateKey, async () => this.call(method, lockedParams), pullBackground);
             }
             if (method === 'message.send') {
                 const encrypt = p.encrypt ?? true;
@@ -220,6 +248,7 @@ export class RpcPipeline {
                         ttl: p.ttl,
                         protectedHeaders: client._protectedHeadersFromParams(p),
                         context: isJsonObject(p.context) ? p.context : undefined,
+                        needRender: p.need_render,
                     }));
                 }
                 client._maybeAppendEchoTraceSend(p);
@@ -234,6 +263,7 @@ export class RpcPipeline {
                         timestamp: p.timestamp,
                         protectedHeaders: client._protectedHeadersFromParams(p),
                         context: isJsonObject(p.context) ? p.context : undefined,
+                        needRender: p.need_render,
                     }));
                 }
                 client._maybeAppendEchoTraceSend(p);
@@ -296,12 +326,12 @@ export class RpcPipeline {
                 }
                 await client._ensureV2SessionReady('group.pull');
                 if (p.window_mode === 'tail') {
-                    return await runWithPullResponseScope(() => client._v2E2EE.pullGroupV2TailInternal(p));
+                    return await runWithPullResponseScope(() => client._v2E2EE.pullGroupV2TailInternal(p, false, true));
                 }
                 const hasExplicitAfterSeq = 'after_seq' in p || 'after_message_seq' in p;
                 const cursorParams = this.explicitGroupCursorParams(p);
                 const ownsCursor = Object.keys(cursorParams).length === 0 || this.groupCursorTargetsCurrentInstance(cursorParams);
-                const pullOpts = { gateLocked: true };
+                const pullOpts = { gateLocked: true, background: rpcBackground };
                 if (hasExplicitAfterSeq)
                     pullOpts.explicitAfterSeq = true;
                 if (p.force === true)
@@ -314,7 +344,7 @@ export class RpcPipeline {
                     pullOpts.wireGroupId = String(p.group_id).trim();
                 if (String(p.group_aid ?? '').trim())
                     pullOpts.groupAid = String(p.group_aid).trim();
-                const messages = await runWithPullResponseScope(() => runWithRpcPriority(() => client._pullGroupV2(String(p.group_id ?? p.group_aid), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, pullOpts)));
+                const messages = await runWithPullResponseScope(() => client._pullGroupV2(String(p.group_id ?? p.group_aid), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, pullOpts));
                 return { messages };
             }
             if (method === 'group.history') {
@@ -347,16 +377,21 @@ export class RpcPipeline {
                 client._clientLog.debug(`thought.get transport call start: method=${method}, params=${client._debugJson(client._messageEnvelopeFieldsForDebug(p))}`);
             }
             const invokeTransport = () => {
-                const request = callTimeout
-                    ? (rpcBackground
-                        ? client._transport.call(method, p, callTimeout, undefined, true)
-                        : client._transport.call(method, p, callTimeout))
-                    : (rpcBackground
-                        ? client._transport.call(method, p, undefined, undefined, true)
-                        : client._transport.call(method, p));
+                const request = onSent
+                    ? client._transport['_callWithSent'](method, p, onSent, callTimeout, undefined, rpcBackground)
+                    : callTimeout
+                        ? (rpcBackground
+                            ? client._transport.call(method, p, callTimeout, undefined, true)
+                            : client._transport.call(method, p, callTimeout))
+                        : (rpcBackground
+                            ? client._transport.call(method, p, undefined, undefined, true)
+                            : client._transport.call(method, p));
                 return this.bindActivePullCancellation(method, p, request);
             };
             let result = await this.transportCallWithIdentityRecovery(invokeTransport, method, p);
+            if (generation === client._delivery?.captureInlineAckGeneration?.()) {
+                this.observeBackgroundPullResponse(method, p, result, pullGateNamespace);
+            }
             const sendResultModeSource = result;
             result = await this.postprocessResult(method, p, result, {
                 skipGroupState: deferGroupReadyPostprocess,
@@ -372,6 +407,10 @@ export class RpcPipeline {
             client._clientLog.debug(`call exit (error): method=${method} elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
+        finally {
+            if (generation === client._delivery?.captureInlineAckGeneration?.())
+                client._delivery?.requestBackgroundPullRecovery?.();
+        }
     }
     preflight(method, params) {
         const client = this.runtime.client;
@@ -383,8 +422,11 @@ export class RpcPipeline {
         }
         const p = { ...(params ?? {}) };
         this.mergeInstanceProtectedHeaders(method, p);
-        const rpcBackground = Boolean(p._rpc_background) || client._backgroundRpcDepth > 0;
+        const rpcBackground = !Boolean(p._rpc_foreground)
+            && (Boolean(p._rpc_background)
+                || (!['message.peers', 'message.pull', 'message.v2.pull', 'group.pull', 'group.v2.pull', 'group.history', 'group.pull_events'].includes(method) && client._backgroundRpcDepth > 0));
         delete p._rpc_background;
+        delete p._rpc_foreground;
         if (method === 'message.send' || method === 'group.send') {
             this.normalizeOutboundMessagePayload(p, method);
             const messageId = String(p.message_id ?? '').trim();
@@ -421,6 +463,9 @@ export class RpcPipeline {
         }
     }
     validateOutboundCall(method, params) {
+        if ((method === 'message.send' || method === 'group.send') && params.need_render !== undefined && typeof params.need_render !== 'boolean') {
+            throw new ValidationError('need_render must be a boolean');
+        }
         if (method === 'message.send') {
             this.validateMessageRecipient(params.to);
             // 校验目标 AID 格式（拒绝 __system__ 等非法格式）
@@ -483,7 +528,7 @@ export class RpcPipeline {
         }
     }
     injectMessageCursorContext(method, params) {
-        if (!['message.pull', 'message.v2.pull', 'message.ack', 'message.v2.ack'].includes(method)) {
+        if (!['message.pull', 'message.v2.pull', 'message.history', 'message.ack', 'message.v2.ack', 'message.peers'].includes(method)) {
             return;
         }
         const client = this.runtime.client;
@@ -496,6 +541,19 @@ export class RpcPipeline {
         }
         params.device_id = client._deviceId;
         params.slot_id = client._slotId;
+        if (client._p2pPeerPullEnabled) {
+            if (params.cursor_scope !== undefined && params.cursor_scope !== 'peer')
+                throw new ValidationError('new SDK requires peer cursor_scope');
+            if (params.sender_aid !== undefined)
+                validateAIDFormat(params.sender_aid, 'sender_aid');
+            params.cursor_scope = 'peer';
+            if ((method === 'message.pull' || method === 'message.v2.pull') && params.sender_aid && !('after_volatile_cursor' in params)) {
+                const cursor = client._delivery.peerVolatilePullCursor(String(params.sender_aid));
+                if (cursor)
+                    params.after_volatile_cursor = cursor;
+            }
+            return;
+        }
         if ((method === 'message.pull' || method === 'message.v2.pull') && !('after_volatile_cursor' in params)) {
             const cursor = String(client._delivery.volatilePullCursor?.() ?? '').trim();
             if (cursor)
@@ -555,6 +613,12 @@ export class RpcPipeline {
                 validateOrgRequestJSON(paramsForHash);
             const paramsJson = method.startsWith('org.') ? new TextDecoder().decode(canonicalClientRequest(paramsForHash)) : stableStringify(paramsForHash);
             const paramsHash = crypto.createHash('sha256').update(paramsJson, 'utf-8').digest('hex');
+            if (params.client_signature !== undefined) {
+                const existing = params.client_signature;
+                if (!isJsonObject(existing) || existing.aid !== aid || existing.cert_fingerprint !== getCertFingerprint(certPem) || existing.params_hash !== paramsHash || typeof existing.timestamp !== 'string' || !/^\d+$/.test(existing.timestamp) || typeof existing.signature !== 'string' || !crypto.verify('SHA256', Buffer.from(`${method}|${aid}|${existing.timestamp}|${paramsHash}`, 'utf-8'), crypto.createPublicKey(certPem), Buffer.from(existing.signature, 'base64')))
+                    throw new Error('已有客户端签名与请求内容不一致');
+                return;
+            }
             const signData = Buffer.from(`${method}|${aid}|${ts}|${paramsHash}`, 'utf-8');
             const privateKey = getSigningPrivateKey(currentAid.privateKeyPem);
             const signature = crypto.sign('SHA256', signData, privateKey);
@@ -595,7 +659,10 @@ export class RpcPipeline {
                 cursor = `after=${String(params.after_seq ?? 0)}`;
             }
             const limit = mode === 'forward' ? (Number(params.limit ?? 50) || 50) : params.limit;
-            return `p2p:${client._aid}|mode=${mode}|cursor=${cursor}|volatile=${String(params.after_volatile_cursor ?? '')}|force=${String(Boolean(params.force))}|limit=${String(limit)}`;
+            if (client._p2pPeerPullEnabled && !params.sender_aid)
+                return '';
+            const namespace = client._p2pPeerPullEnabled ? client._delivery.peerNamespace(String(params.sender_aid)) : `p2p:${client._aid}`;
+            return `${namespace}|mode=${mode}|cursor=${cursor}|volatile=${String(params.after_volatile_cursor ?? '')}|force=${String(Boolean(params.force))}|limit=${String(limit)}`;
         }
         if (method === 'group.pull' || method === 'group.v2.pull' || method === 'group.history') {
             const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
@@ -640,14 +707,15 @@ export class RpcPipeline {
         void key;
         return 'pull';
     }
-    pullGateState(key) {
-        const name = this.pullGateName(key);
+    pullGateState(key, namespaceOnly = false) {
+        const name = namespaceOnly ? 'pull-namespace' : this.pullGateName(key);
         let state = this.pullGateStates.get(name);
         if (!state) {
-            state = { active: null, foreground: [], background: [], byKey: new Map(), lifecycle: new Map(), watchdog: null };
+            state = { networkLimited: !namespaceOnly, activeByNamespace: new Map(), foreground: [], background: [], backgroundPeerDispatches: 0, byKey: new Map(), lifecycle: new Map(), watchdog: null };
             this.pullGateStates.set(name, state);
         }
-        this.startPullGateWatchdog(state, name);
+        if (state.networkLimited)
+            this.startPullGateWatchdog(state, name);
         return state;
     }
     pullGateOperationTimeoutMs() {
@@ -675,23 +743,25 @@ export class RpcPipeline {
         }
     }
     checkPullGate(state, name) {
-        const active = state.active;
-        if (!active) {
+        const activeJobs = [...state.activeByNamespace.values()];
+        if (activeJobs.length === 0) {
             this.drainPullGate(state);
             return;
         }
-        if (!active.pullingStartedAt || Date.now() - active.pullingStartedAt < this.pullGateOperationTimeoutMs())
-            return;
-        if (active.timedOut)
-            return;
-        active.timedOut = true;
-        active.invalidated = true;
-        active.cancel?.();
-        const timeout = new TimeoutError(`pull gate timeout: ${active.namespace}`, { retryable: true });
-        this.runtime.client._clientLog.warn(`pull gate watchdog timeout: gate=${name} key=${active.key} elapsed=${Date.now() - active.pullingStartedAt}ms`);
-        // 仅拒绝当前调用方；取消不敏感的 operation 仍可能运行，必须等其
-        // 真正 settle 后才释放 active，避免与后续 Pull 并发修改游标。
-        active.reject(timeout);
+        for (const active of activeJobs) {
+            if (!active.pullingStartedAt || Date.now() - active.pullingStartedAt < this.pullGateOperationTimeoutMs())
+                continue;
+            if (active.timedOut)
+                continue;
+            active.timedOut = true;
+            active.invalidated = true;
+            active.cancel?.();
+            const timeout = new TimeoutError(`pull gate timeout: ${active.namespace}`, { retryable: true });
+            this.runtime.client._clientLog.warn(`pull gate watchdog timeout: gate=${name} key=${active.key} elapsed=${Date.now() - active.pullingStartedAt}ms`);
+            // 仅拒绝当前调用方；取消不敏感的 operation 仍可能运行，必须等其
+            // 真正 settle 后才释放 active，避免与后续 Pull 并发修改游标。
+            active.reject(timeout);
+        }
     }
     pullScopeKey(key) {
         return key.split('|', 1)[0] ?? key;
@@ -706,7 +776,7 @@ export class RpcPipeline {
         if (typeof cancel !== 'function' || !key)
             return request;
         const state = this.pullGateStates.get(this.pullGateName(key));
-        const active = state?.active;
+        const active = [...(state?.activeByNamespace.values() ?? [])].find((candidate) => candidate.key === key);
         if (!active || active.key !== key || active.timedOut || active.invalidated)
             return request;
         const boundCancel = () => cancel.call(request);
@@ -723,9 +793,11 @@ export class RpcPipeline {
     }
     hasPullActivity(namespace, includePending = true) {
         const ns = String(namespace ?? '').trim();
-        if ((!ns.startsWith('p2p:') && !ns.startsWith('group:')) || this.hasInlineRealtimeGuard(ns))
+        if ((!ns.startsWith('p2p:') && !ns.startsWith('p2p.peer.v1/') && !ns.startsWith('group:')) || this.hasInlineRealtimeGuard(ns))
             return true;
         const client = this.runtime.client;
+        if (client._delivery?.hasPeerPageActivity?.(ns))
+            return true;
         if ((client._pullResponseKeys.get(ns) ?? 0) > 0)
             return true;
         if (includePending && Number(client._pendingP2pPullUpper?.get?.(ns) ?? 0) > 0)
@@ -744,15 +816,15 @@ export class RpcPipeline {
                 return true;
         }
         for (const state of this.pullGateStates.values()) {
-            const jobs = [state.active, ...state.foreground, ...state.background];
-            if (jobs.some((job) => job !== null && this.pullScopeKey(job.key) === ns))
+            const jobs = [...state.activeByNamespace.values(), ...state.foreground, ...state.background];
+            if (jobs.some((job) => this.pullScopeKey(job.key) === ns))
                 return true;
         }
         return false;
     }
     async tryRunInlineRealtime(namespace, seq, operation) {
         const ns = String(namespace ?? '').trim();
-        if ((!ns.startsWith('p2p:') && !ns.startsWith('group:'))
+        if ((!ns.startsWith('p2p:') && !ns.startsWith('p2p.peer.v1/') && !ns.startsWith('group:'))
             || !Number.isSafeInteger(seq) || seq <= 0 || typeof operation !== 'function'
             || this.hasPullActivity(ns)) {
             return { acquired: false };
@@ -763,12 +835,11 @@ export class RpcPipeline {
         }
         finally {
             this.inlineRealtimeScopes.delete(ns);
-            const state = this.pullGateStates.get(this.pullGateName(ns));
-            if (state) {
+            for (const state of this.pullGateStates.values()) {
                 this.drainPullGate(state);
-                this.runtime.client._delivery?.onPullGateIdle?.(ns);
                 this.armQueuedPullTimers(state);
             }
+            this.runtime.client._delivery?.onPullGateIdle?.(ns);
         }
     }
     tryAcquirePullGate(key) {
@@ -808,8 +879,10 @@ export class RpcPipeline {
         const ns = this.pullScopeKey(namespace);
         if (!ns)
             return true;
-        const active = this.pullGateStates.get(this.pullGateName(ns))?.active;
-        return !active || active.namespace !== ns || (!active.timedOut && !active.invalidated);
+        return [...this.pullGateStates.values()].every((state) => {
+            const active = state.activeByNamespace.get(ns);
+            return !active || active.namespace !== ns || (!active.timedOut && !active.invalidated);
+        });
     }
     invalidatePulls() {
         if (this.pullInvalidationWait)
@@ -819,8 +892,8 @@ export class RpcPipeline {
         const waits = [];
         for (const state of this.pullGateStates.values()) {
             const jobs = new Set();
-            if (state.active)
-                jobs.add(state.active);
+            for (const active of state.activeByNamespace.values())
+                jobs.add(active);
             for (const job of state.foreground)
                 jobs.add(job);
             for (const job of state.background)
@@ -842,6 +915,7 @@ export class RpcPipeline {
             }
             state.foreground = state.foreground.filter((job) => !jobs.has(job));
             state.background = state.background.filter((job) => !jobs.has(job));
+            state.backgroundPeerDispatches = 0;
             for (const [key, job] of state.byKey.entries()) {
                 if (jobs.has(job) && !job.running)
                     state.byKey.delete(key);
@@ -860,7 +934,10 @@ export class RpcPipeline {
     pullInvalidationInProgress() {
         return this.pullInvalidationWait !== null;
     }
-    async runPullSerialized(key, operation, background = false) {
+    async runPullNamespaceSerialized(key, operation, background = false) {
+        return await this.runPullSerialized(key, operation, background, true);
+    }
+    async runPullSerialized(key, operation, background = false, namespaceOnly = false) {
         if (this.runtime.client._dispatcher?._isApplicationHandler?.()) {
             throw new Error('pull cannot wait inside an application handler');
         }
@@ -876,9 +953,9 @@ export class RpcPipeline {
                 throw error;
             }
         }
-        const state = this.pullGateState(key);
+        const state = this.pullGateState(key, namespaceOnly);
         const namespace = this.pullScopeKey(key);
-        const active = state.active?.key === key && !state.active.timedOut && !state.active.invalidated ? state.active : null;
+        const active = [...state.activeByNamespace.values()].find((job) => job.key === key && !job.timedOut && !job.invalidated) ?? null;
         const queuedForeground = state.foreground.find((job) => job.key === key && !job.timedOut && !job.invalidated);
         const queuedBackground = state.background.find((job) => job.key === key && !job.timedOut && !job.invalidated);
         const existing = background
@@ -920,7 +997,8 @@ export class RpcPipeline {
         queue.push(job);
         state.byKey.set(key, job);
         this.drainPullGate(state);
-        this.checkPullGate(state, this.pullGateName(key));
+        if (state.networkLimited)
+            this.checkPullGate(state, this.pullGateName(key));
         return await promise;
     }
     async executePullOperation(operation, background) {
@@ -938,8 +1016,8 @@ export class RpcPipeline {
             return;
         const state = this.pullGateState(key);
         const namespace = this.pullScopeKey(key);
-        const job = state.active?.key === key ? state.active : null;
-        if (!job || state.active !== job || job.timedOut || job.invalidated)
+        const job = [...state.activeByNamespace.values()].find((candidate) => candidate.key === key) ?? null;
+        if (!job || job.timedOut || job.invalidated)
             return;
         const replacementKey = String(nextKey || key);
         if (state.byKey.get(job.key) === job)
@@ -958,7 +1036,7 @@ export class RpcPipeline {
         state.lifecycle.set(namespace, 'pulled');
         job.suspended = true;
         job.resume = new Promise((resolve) => { job.resumeResolve = resolve; });
-        state.active = null;
+        state.activeByNamespace.delete(namespace);
         (job.background ? state.background : state.foreground).push(job);
         this.drainPullGate(state);
         if (job.resume) {
@@ -978,67 +1056,93 @@ export class RpcPipeline {
         if (!ns)
             return;
         const state = this.pullGateStates.get(this.pullGateName(ns));
-        if (!state || state.active?.namespace !== ns)
+        if (!state || !state.activeByNamespace.has(ns))
             return;
         state.lifecycle.set(ns, lifecycle);
     }
     drainPullGate(state) {
-        if (state.active)
-            return;
-        const takeRunnable = (queue) => {
-            const index = queue.findIndex((candidate) => !this.hasInlineRealtimeGuard(this.pullScopeKey(candidate.key)));
-            return index >= 0 ? queue.splice(index, 1)[0] : undefined;
+        const peerForward = (job) => job.background && job.namespace.startsWith('p2p.peer.v1/')
+            && job.key.includes('|mode=forward|') && !job.key.includes('|force=true|');
+        const priority = (job) => peerForward(job)
+            ? this.runtime.client._delivery?.peerPullPriority?.(job.namespace) ?? null : null;
+        const runnable = (candidate) => (!this.hasInlineRealtimeGuard(this.pullScopeKey(candidate.key))
+            && !state.activeByNamespace.has(candidate.namespace));
+        const takeRunnable = (queue, background = false) => {
+            let index = queue.findIndex(runnable);
+            if (index < 0)
+                return;
+            if (background && peerForward(queue[index])
+                && (state.backgroundPeerDispatches + 1) % _INTERNAL_MESSAGE_FLOW_LIMITS.pullMaxInflight !== 0) {
+                let best = priority(queue[index]);
+                if (best !== null) {
+                    for (let next = index + 1; next < queue.length; next += 1) {
+                        const hint = priority(queue[next]);
+                        if (hint === null)
+                            break;
+                        if (runnable(queue[next]) && hint < best) {
+                            best = hint;
+                            index = next;
+                        }
+                    }
+                }
+            }
+            const job = queue.splice(index, 1)[0];
+            if (background && peerForward(job))
+                state.backgroundPeerDispatches += 1;
+            return job;
         };
-        const foregroundJob = takeRunnable(state.foreground);
-        const foregroundDrained = foregroundJob !== undefined && state.foreground.length === 0;
-        const job = foregroundJob ?? takeRunnable(state.background);
-        if (!job)
-            return;
-        state.active = job;
-        this.runtime.client._delivery?.syncStarted?.(job.namespace);
-        if (foregroundDrained)
-            this.runtime.client._delivery?.onForegroundPullsDrained?.();
-        if (job.timer) {
-            clearTimeout(job.timer);
-            job.timer = null;
-        }
-        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;
-        const operationPromise = this.executePullOperation(job.operation, job.background);
-        let failed = false;
-        void operationPromise
-            .then((value) => { if (!job.timedOut && !job.invalidated)
-            job.resolve(value); }, (error) => {
-            failed = true;
-            if (!job.timedOut && !job.invalidated)
-                job.reject(error);
-        })
-            .finally(() => {
-            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);
-            job.settledResolve?.();
-            job.settledResolve = null;
-            if (!job.invalidated) {
-                this.runtime.client._delivery?.onPullGateIdle?.(job.namespace);
+        while (state.activeByNamespace.size < _INTERNAL_MESSAGE_FLOW_LIMITS.pullMaxInflight) {
+            const foregroundJob = takeRunnable(state.foreground);
+            const foregroundDrained = foregroundJob !== undefined && state.foreground.length === 0;
+            const job = foregroundJob ?? takeRunnable(state.background, true);
+            if (!job)
+                break;
+            state.activeByNamespace.set(job.namespace, job);
+            this.runtime.client._delivery?.syncStarted?.(job.namespace);
+            if (foregroundDrained)
+                this.runtime.client._delivery?.onForegroundPullsDrained?.();
+            if (job.timer) {
+                clearTimeout(job.timer);
+                job.timer = null;
             }
-            if (failed || job.invalidated)
-                this.runtime.client._delivery?.onPullAborted?.();
-            this.notifyPullDrainedIfIdle();
-        });
+            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?.();
+                continue;
+            }
+            job.running = true;
+            const operationPromise = this.executePullOperation(job.operation, state.networkLimited && job.background);
+            let failed = false;
+            void operationPromise
+                .then((value) => { if (!job.timedOut && !job.invalidated)
+                job.resolve(value); }, (error) => {
+                failed = true;
+                if (!job.timedOut && !job.invalidated)
+                    job.reject(error);
+            })
+                .finally(() => {
+                state.lifecycle.set(job.namespace, 'idle');
+                if (state.activeByNamespace.get(job.namespace) === job)
+                    state.activeByNamespace.delete(job.namespace);
+                if (state.byKey.get(job.key) === job)
+                    state.byKey.delete(job.key);
+                this.drainPullGate(state);
+                job.settledResolve?.();
+                job.settledResolve = null;
+                if (!job.invalidated) {
+                    this.runtime.client._delivery?.onPullGateIdle?.(job.namespace);
+                }
+                if (failed || job.invalidated)
+                    this.runtime.client._delivery?.onPullAborted?.();
+                this.notifyPullDrainedIfIdle();
+            });
+        }
     }
     notifyPullDrainedIfIdle() {
         if (this.pullDrainedCheckQueued)
@@ -1054,7 +1158,7 @@ export class RpcPipeline {
     }
     notifyPullDrainedIfIdleStable() {
         for (const state of this.pullGateStates.values()) {
-            if (state.active || state.foreground.length > 0 || state.background.length > 0)
+            if (state.activeByNamespace.size > 0 || state.foreground.length > 0 || state.background.length > 0)
                 return;
         }
         const client = this.runtime.client;
@@ -1087,9 +1191,34 @@ export class RpcPipeline {
                 request = client._transport.call(method, payload);
             return this.bindActivePullCancellation(method, payload, request, pullGateKey);
         };
-        const result = await this.transportCallWithIdentityRecovery(invokeTransport, method, payload);
-        this.throwIfPullInvalidated(this.pullScopeKey(pullGateKey || this.pullGateKeyForCall(method, payload)));
-        return result;
+        const generation = client._delivery?.captureInlineAckGeneration?.();
+        try {
+            const result = await this.transportCallWithIdentityRecovery(invokeTransport, method, payload);
+            this.throwIfPullInvalidated(this.pullScopeKey(pullGateKey || this.pullGateKeyForCall(method, payload)));
+            if (generation === client._delivery?.captureInlineAckGeneration?.()) {
+                this.observeBackgroundPullResponse(method, payload, result, pullGateKey);
+            }
+            return result;
+        }
+        finally {
+            if (generation === client._delivery?.captureInlineAckGeneration?.())
+                client._delivery?.requestBackgroundPullRecovery?.();
+        }
+    }
+    observeBackgroundPullResponse(method, params, result, key = '') {
+        if (!['message.pull', 'message.v2.pull', 'group.pull', 'group.v2.pull', 'group.pull_events'].includes(method)
+            || params.force === true || params.window_mode === 'tail')
+            return;
+        const client = this.runtime.client;
+        if (method.startsWith('group.') && !this.groupCursorTargetsCurrentInstance(params))
+            return;
+        const explicitCursor = this.explicitGroupCursorParams(params);
+        if (method.startsWith('group.') && !this.groupCursorTargetsCurrentInstance(explicitCursor))
+            return;
+        const ns = this.pullScopeKey(key) || (method === 'group.pull_events'
+            ? `group_event:${String(params.group_id ?? params.group_aid ?? '')}`
+            : method.startsWith('group.') ? `group:${String(params.group_id ?? params.group_aid ?? '')}` : `p2p:${client._aid}`);
+        client._delivery?.observeBackgroundPullResponse?.(ns, Number(params.after_seq ?? params.after_event_seq ?? 0), result, Number(params.limit ?? 50));
     }
     async transportCallWithIdentityRecovery(operation, method, params) {
         try {