@agentunion/fastaun-browser 0.5.20 → 0.5.21

package/dist/tools/cross-sdk-agent.js

@@ -8,7 +8,7 @@ import * as path from 'node:path';
 import { URL, fileURLToPath } from 'node:url';
 import { AID, AIDStore, AUNClient, __version__ } from '../index.js';
 import { publicKeyFingerprint } from '../cert-utils.js';
-import { StateError } from '../errors.js';
+import { StateError, TimeoutError } from '../errors.js';
 import { OwnershipStorageAdapter } from '../ownership-v21.js';
 import { ownershipErrorCode, ownershipTaskResult } from '../ownership-workflow.js';
 import { canonicalJson, digest, buildRequestBinding, verifyMembershipBinding, ProtocolError } from '../org-protocol.js';
@@ -141,14 +141,28 @@ export class CrossSdkJsAgent {
     rawPushObservations = [];
     rawPushObservationId = '';
     rawPushRpcMethods = [];
+    eventLedger = [];
+    rpcSpans = [];
+    observationGeneration = 0;
+    pullBarrier = null;
+    rpcFailures = [];
+    messageOperations = new Map();
     rpcObservedTransports = new WeakSet();
+    rpcObservedPipelines = new WeakSet();
+    rpcObservedPulls = new WeakMap();
     groupChangedEvents = [];
     groupInviteEvents = [];
     readStateEvents = [];
+    peersSnapshots = [];
     ownershipEvents = [];
     traces = new Map();
     sendResults = new Map();
     inlineRealtimePayloadV1 = true;
+    batchEventMode = false;
+    batchEvents = [];
+    singleEventCounts = { 'message.received': 0, 'group.message_created': 0, 'group.changed': 0 };
+    clientEventsBound = new WeakSet();
+    batchEventHandlers = new WeakMap();
     constructor() {
         this.client = this.newClient();
     }
@@ -166,28 +180,41 @@ export class CrossSdkJsAgent {
     }
     bindClientEvents() {
         this.installTransportRpcObserver();
+        if (this.clientEventsBound.has(this.client)) {
+            this.syncBatchEventHandlers();
+            return;
+        }
+        this.clientEventsBound.add(this.client);
         this.client.on('_raw.message.received', (data) => this.storeRawPushObservation('_raw.message.received', 'p2p', 'legacy', data));
         this.client.on('_raw.peer.v2.message_received', (data) => this.storeRawPushObservation('_raw.peer.v2.message_received', 'p2p', 'v2', data));
         this.client.on('_raw.group.message_created', (data) => this.storeRawPushObservation('_raw.group.message_created', 'group', 'legacy', data));
         this.client.on('_raw.group.v2.message_created', (data) => this.storeRawPushObservation('_raw.group.v2.message_created', 'group', 'v2', data));
         this.client.on('_raw.group.changed', (data) => this.storeRawGroupChangedObservation(data));
         this.client.on('message.received', (msg) => {
-            void this.storeInboxItem(this.normalizeMessage(msg, true));
+            this.singleEventCounts['message.received']++;
+            this.storeApplicationEvent('message.received', msg);
         });
         this.client.on('message.undecryptable', (msg) => {
             void this.storeInboxItem(this.normalizeMessage(msg, false, 'undecryptable'));
         });
         this.client.on('group.message_created', (msg) => {
-            void this.storeGroupInboxItem(this.normalizeGroupMessage(msg, true));
+            this.singleEventCounts['group.message_created']++;
+            this.storeApplicationEvent('group.message_created', msg);
         });
         this.client.on('group.message_undecryptable', (msg) => {
             void this.storeGroupInboxItem(this.normalizeGroupMessage(msg, false, 'undecryptable'));
         });
-        this.client.on('group.changed', (data) => this.storeGroupChangedPublicEvent(data));
+        this.client.on('group.changed', (data) => {
+            this.singleEventCounts['group.changed']++;
+            this.storeApplicationEvent('group.changed', data);
+        });
         this.client.on('group.invite_received', (data) => this.storeGroupInviteEvent(data));
         for (const event of ['message.read_changed', 'group.read_changed', 'read_state_sync']) {
             this.client.on(event, (payload) => { this.readStateEvents.push({ event, payload: jsonSafe(payload) }); });
         }
+        this.client.on('message.peers_snapshot', (payload) => {
+            this.peersSnapshots.push({ event: 'message.peers_snapshot', payload: jsonSafe(payload) });
+        });
         for (const event of ['ownership.request', 'ownership.action_required', 'ownership.progress', 'ownership.completed', 'ownership.rejected', 'ownership.stopped', 'ownership.error']) {
             this.client.on(event, (payload) => { this.ownershipEvents.push({ event, payload: jsonSafe(payload) }); });
         }
@@ -198,16 +225,89 @@ export class CrossSdkJsAgent {
                 this.recordTrace(textOf(payload.org_id), { stage: event, payload });
             });
         }
+        this.syncBatchEventHandlers();
+    }
+    syncBatchEventHandlers() {
+        const bound = this.batchEventHandlers.get(this.client);
+        if (!this.batchEventMode) {
+            if (bound)
+                for (const [event, handler] of bound)
+                    this.client.off(event, handler);
+            this.batchEventHandlers.delete(this.client);
+            return;
+        }
+        if (bound)
+            return;
+        const handlers = new Map();
+        for (const event of ['message.batch', 'group.message_batch', 'group.event_batch']) {
+            const handler = (value) => {
+                const data = jsonObjectOf(value) ?? {};
+                const items = JSON.parse(stableStringify(jsonSafe(Array.isArray(data.items) ? data.items : [])));
+                this.batchEvents.push({ observation_id: this.rawPushObservationId, time_ms: Date.now(), event, namespace: textOf(data.namespace), source: textOf(data.source), items });
+                for (const item of items)
+                    this.storeApplicationEvent(textOf(item.event), item.payload);
+            };
+            handlers.set(event, handler);
+            this.client.on(event, handler);
+        }
+        this.batchEventHandlers.set(this.client, handlers);
+    }
+    storeApplicationEvent(event, value) {
+        if (event === 'message.received') {
+            this.storePublicMessageEvent(event, 'p2p', value);
+            void this.storeInboxItem(this.normalizeMessage(value, true));
+        }
+        else if (event === 'group.message_created') {
+            this.storePublicMessageEvent(event, 'group', value);
+            void this.storeGroupInboxItem(this.normalizeGroupMessage(value, true));
+        }
+        else if (event === 'group.changed')
+            this.storeGroupChangedPublicEvent(value);
     }
     installTransportRpcObserver() {
+        const client = this.client;
+        const pipeline = client._rpcPipeline;
+        this.rpcObservedPipelines ??= new WeakSet();
+        this.rpcObservedPulls ??= new WeakMap();
+        if (pipeline?.bindActivePullCancellation && !this.rpcObservedPipelines.has(pipeline)) {
+            const originalBind = pipeline.bindActivePullCancellation;
+            this.rpcObservedPipelines.add(pipeline);
+            pipeline.bindActivePullCancellation = (method, params, request, gateKey = '') => {
+                const result = originalBind.call(pipeline, method, params, request, gateKey);
+                const observed = this.rpcObservedPulls.get(request);
+                if (!this.pullBarrier?.preserve || !observed || !['message.pull', 'message.v2.pull'].includes(method)
+                    || !textOf(params.sender_aid) || typeof client._delivery?.peerNamespace !== 'function')
+                    return result;
+                const key = gateKey || pipeline.pullGateKeyForCall(method, params);
+                const namespace = client._delivery?.peerNamespace(textOf(params.sender_aid));
+                const owners = [...pipeline.pullGateStates.values()].flatMap((state) => [...state.activeByNamespace.values()])
+                    .filter((job) => job.key === key && job.namespace === namespace && job.running && !job.timedOut && !job.invalidated && job.cancel);
+                if (owners.length === 1)
+                    observed.owner = { job: owners[0], cancel: owners[0].cancel, key, namespace: namespace };
+                return result;
+            };
+        }
         const transport = this.client._transport;
         transport?.setTraceMode('diag');
         if (!transport?.call || this.rpcObservedTransports.has(transport))
             return;
         const originalCall = transport.call;
+        const originalClose = transport.close;
         this.rpcObservedTransports.add(transport);
-        transport.call = async (method, params, timeout, trace, background) => {
+        if (originalClose)
+            transport.close = async () => {
+                if (!this.pullBarrier?.preserve)
+                    this.releasePullBarrier();
+                return await originalClose.call(transport);
+            };
+        transport.call = (method, params, timeout, trace, background) => {
             this.storeRawPushRpcMethod({ type: 'rpc', method, request_window: this.rawPushRequestWindow(params) });
+            const generation = this.observationGeneration;
+            const span = this.startRpcSpan(method, params);
+            const barrier = this.pullBarrier;
+            const controller = new AbortController();
+            let originalPromise;
+            const observed = {};
             let requestParams = params;
             if (method === 'auth.connect' && !this.inlineRealtimePayloadV1 && jsonObjectOf(params)) {
                 const request = { ...jsonObjectOf(params) };
@@ -218,9 +318,196 @@ export class CrossSdkJsAgent {
                 }
                 requestParams = request;
             }
-            return await originalCall.call(transport, method, requestParams, timeout, trace, background);
+            const observedPromise = (async () => {
+                try {
+                    originalPromise = originalCall.call(transport, method, requestParams, timeout, trace, background);
+                    const result = await originalPromise;
+                    if (span && generation === this.observationGeneration)
+                        this.finishRpcResponse(span, result);
+                    const isPull = ['message.pull', 'message.v2.pull', 'group.pull', 'group.v2.pull', 'group.pull_events'].includes(method);
+                    const isP2PPull = ['message.pull', 'message.v2.pull'].includes(method);
+                    if (barrier && generation === this.observationGeneration && (isPull || barrier.method === method) && (barrier.scope !== 'p2p' || isP2PPull || barrier.method === method)
+                        && (!barrier.sender || barrier.sender === span?.sender_aid) && (!barrier.method || barrier.method === method)) {
+                        const duration = (typeof timeout === 'number' && timeout > 0 ? timeout : transport._timeout ?? 35) * 1000;
+                        await this.waitPullBarrier(barrier, controller.signal, Math.max(1, duration - (Date.now() - Number(span?.start_ms ?? Date.now()))), method, span, observed.owner);
+                    }
+                    if (span && generation === this.observationGeneration) {
+                        this.injectRPCFailure(method, span);
+                        span.success = true;
+                    }
+                    return result;
+                }
+                catch (error) {
+                    if (span && generation === this.observationGeneration) {
+                        span.error = true;
+                        span.success = false;
+                    }
+                    throw error;
+                }
+                finally {
+                    if (span && generation === this.observationGeneration)
+                        span.end_ms = Date.now();
+                }
+            })();
+            observedPromise.cancel = () => { controller.abort(); originalPromise?.cancel?.(); };
+            this.rpcObservedPulls.set(observedPromise, observed);
+            return observedPromise;
         };
     }
+    storePublicMessageEvent(event, scope, value) {
+        const data = jsonObjectOf(value) ?? {};
+        const internal = this.client;
+        const payload = JSON.parse(stableStringify(jsonSafe(data.payload ?? null)));
+        this.eventLedger.push({
+            observation_id: this.rawPushObservationId, scope, event, event_index: this.eventLedger.length + 1,
+            time_ms: Date.now(), receiver_aid: this.aid, device_id: textOf(internal._deviceId), slot_id: textOf(internal._slotId || this.slotId),
+            sender_aid: textOf(data.from ?? data.from_aid ?? data.sender_aid), group_id: textOf(data.group_id),
+            message_id: textOf(data.message_id ?? data.id), seq: Number(data.seq ?? data.message_seq ?? data.msg_seq ?? 0) || 0,
+            storage: textOf(data.storage), volatile_cursor: textOf(data.volatile_cursor),
+            payload, payload_sha256: sha256Json(payload), need_render: data.need_render !== false,
+            ...(Object.prototype.hasOwnProperty.call(data, 'mention_mode') ? { mention_mode: data.mention_mode } : {}),
+        });
+    }
+    startRpcSpan(method, value) {
+        if (!['message.pull', 'message.v2.pull', 'group.pull', 'group.v2.pull', 'group.events', 'group.pull_events', 'message.peers', 'message.ack', 'message.v2.ack', 'group.ack', 'group.v2.ack', 'group.ack_messages', 'group.ack_events'].includes(method))
+            return null;
+        const params = jsonObjectOf(value) ?? {};
+        const senderAid = textOf(params.sender_aid ?? params.peer_aid).trim();
+        const groupId = textOf(params.group_id ?? params.group_aid).trim();
+        const groupEvent = ['group.events', 'group.pull_events', 'group.ack_events'].includes(method);
+        const group = method.startsWith('group.');
+        const span = {
+            observation_id: this.rawPushObservationId, scope: group ? 'group' : 'p2p', span_id: this.rpcSpans.length + 1,
+            boundary: 'transport_call', method, start_ms: Date.now(), response_ms: null, end_ms: null, success: null,
+            cursor_scope: textOf(params.cursor_scope) || (group ? groupEvent ? 'group_event' : 'group' : senderAid || method === 'message.peers' ? 'peer' : 'global'),
+            sender_aid: senderAid, group_id: groupId,
+            namespace: group ? groupId ? `${groupEvent ? 'group_event' : 'group'}:${groupId}` : '' : method === 'message.peers' ? '' : this.syncNamespace('p2p', '', senderAid),
+            request_window: this.rpcSpanRequestWindow(params), response_message_count: 0, response_volatile_count: 0, response_event_count: 0, response_peer_count: 0, response_item_keys: [], response_event_keys: [],
+            has_more: null, has_more_persistent: null, has_more_volatile: null, persistent_has_more: null, volatile_has_more: null,
+            effective_ack_seq: null, peer_ack_seq: null, server_ack_seq: null, error: false,
+        };
+        this.rpcSpans.push(span);
+        return span;
+    }
+    rpcSpanRequestWindow(params) {
+        const out = this.rawPushRequestWindow(params);
+        for (const key of ['before_seq', 'until_seq', 'after_message_seq', 'after_event_seq', 'snapshot_head_seq', 'seq', 'up_to_seq', 'msg_seq', 'event_seq']) {
+            const value = params[key];
+            if (typeof value === 'number' && Number.isSafeInteger(value))
+                out[key] = value;
+        }
+        for (const key of ['after_volatile_cursor', 'volatile_cursor', 'mode', 'after_sender_aid', 'peer_mode', 'directory_mode'])
+            if (typeof params[key] === 'string')
+                out[key] = params[key];
+        for (const key of ['force', 'pending_only'])
+            if (typeof params[key] === 'boolean')
+                out[key] = params[key];
+        for (const key of ['volatile_cursors', 'volatile_ids'])
+            if (Array.isArray(params[key]))
+                out[key] = params[key].filter((item) => typeof item === 'string');
+        return out;
+    }
+    finishRpcResponse(span, value) {
+        const result = jsonObjectOf(value) ?? {};
+        span.response_ms = Date.now();
+        const messages = Array.isArray(result.messages) ? result.messages : [];
+        span.response_message_count = messages.length;
+        span.response_volatile_count = messages.filter((item) => jsonObjectOf(item)?.storage === 'volatile').length;
+        span.response_event_count = Array.isArray(result.events) ? result.events.length : 0;
+        span.response_peer_count = Array.isArray(result.peers) ? result.peers.length : 0;
+        const sequenceOf = (...values) => values.find((value) => typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value)) ?? 0;
+        const itemKeys = new Map();
+        for (const key of ['messages', 'volatile_messages', 'volatile'])
+            for (const value of Array.isArray(result[key]) ? result[key] : []) {
+                const item = jsonObjectOf(value) ?? {};
+                const cursor = textOf(item.volatile_cursor);
+                const identity = { message_id: textOf(item.message_id ?? item.id), seq: sequenceOf(item.seq, item.message_seq, item.msg_seq), storage: textOf(item.storage) || (cursor ? 'volatile' : 'persistent'), volatile_cursor: cursor };
+                itemKeys.set(stableStringify(identity), identity);
+            }
+        span.response_item_keys = [...itemKeys.values()];
+        span.response_event_keys = (Array.isArray(result.events) ? result.events : []).map((value) => {
+            const item = jsonObjectOf(value) ?? {};
+            return { event_id: textOf(item.event_id), event_seq: sequenceOf(item.event_seq, item.seq) };
+        });
+        span.has_more = typeof result.has_more === 'boolean' ? result.has_more : null;
+        span.has_more_persistent = typeof result.has_more_persistent === 'boolean' ? result.has_more_persistent : typeof result.persistent_has_more === 'boolean' ? result.persistent_has_more : null;
+        span.has_more_volatile = typeof result.has_more_volatile === 'boolean' ? result.has_more_volatile : typeof result.volatile_has_more === 'boolean' ? result.volatile_has_more : null;
+        span.persistent_has_more = typeof result.persistent_has_more === 'boolean' ? result.persistent_has_more : null;
+        span.volatile_has_more = typeof result.volatile_has_more === 'boolean' ? result.volatile_has_more : null;
+        const safeSeq = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+        span.peer_ack_seq = safeSeq(result.peer_ack_seq);
+        span.server_ack_seq = safeSeq(result.server_ack_seq);
+        span.effective_ack_seq = safeSeq(result.peer_ack_seq ?? result.effective_ack_seq ?? result.ack_seq ?? result.server_ack_seq ?? jsonObjectOf(result.cursor)?.current_seq ?? result.cursor);
+        const volatileAck = jsonObjectOf(result.volatile_ack);
+        if (volatileAck) {
+            const ack = {};
+            for (const key of ['accepted', 'expired'])
+                if (typeof volatileAck[key] === 'number' && Number.isSafeInteger(volatileAck[key]))
+                    ack[key] = volatileAck[key];
+            if (typeof volatileAck.storage === 'string')
+                ack.storage = volatileAck.storage;
+            span.volatile_ack = ack;
+        }
+    }
+    releasePullBarrier() {
+        if (!this.pullBarrier || this.pullBarrier.released)
+            return;
+        this.pullBarrier.released = true;
+        this.pullBarrier.release();
+    }
+    injectRPCFailure(method, span) {
+        const failure = this.rpcFailures?.find((item) => !item.hit && item.method === method && item.sender_aid === span.sender_aid);
+        if (!failure)
+            return;
+        failure.hit = true;
+        span.injected_failure = failure.kind ?? 'error';
+        if (failure.kind === 'timeout')
+            throw new TimeoutError('cross-sdk 响应后一次超时');
+        throw new Error('cross-sdk 响应后一次失败');
+    }
+    resetObservationLedgers(count = 0, scope = 'all', controls = {}) {
+        this.releasePullBarrier();
+        this.observationGeneration++;
+        this.eventLedger = [];
+        this.rpcSpans = [];
+        this.batchEvents = [];
+        this.singleEventCounts = { 'message.received': 0, 'group.message_created': 0, 'group.changed': 0 };
+        this.rpcFailures = Array.isArray(controls.rpc_failures) ? controls.rpc_failures.map((item) => ({ ...jsonObjectOf(item) })) : [];
+        let release;
+        const promise = new Promise((resolve) => { release = resolve; });
+        this.pullBarrier = { target: count, admitted: 0, waiting: 0, released: count <= 0, scope: scope === 'p2p' ? 'p2p' : 'all', promise, release,
+            sender: textOf(controls.pull_barrier_sender_aid), method: textOf(controls.pull_barrier_method), preserve: controls.preserve_pull_barrier === true };
+    }
+    async waitPullBarrier(barrier, signal, timeout, method, span, owner) {
+        if (barrier.released || barrier.admitted >= barrier.target)
+            return;
+        if (signal.aborted && !barrier.preserve)
+            throw new Error('transport call cancelled');
+        barrier.admitted++;
+        barrier.waiting++;
+        if (barrier.preserve) {
+            barrier.heldMethod = method;
+            barrier.owner = owner;
+            barrier.span = span ?? undefined;
+        }
+        let timer;
+        let onAbort;
+        try {
+            await Promise.race([barrier.promise, new Promise((_resolve, reject) => {
+                    onAbort = () => reject(new Error('transport call cancelled'));
+                    if (!barrier.preserve)
+                        signal.addEventListener('abort', onAbort, { once: true });
+                    timer = setTimeout(() => reject(new Error('pull barrier timed out')), timeout);
+                })]);
+        }
+        finally {
+            barrier.waiting--;
+            if (timer)
+                clearTimeout(timer);
+            if (onAbort)
+                signal.removeEventListener('abort', onAbort);
+        }
+    }
     storeRawPushObservation(rawEvent, scope, defaultKind, value) {
         const data = jsonObjectOf(value) ?? {};
         const hasInline = Object.prototype.hasOwnProperty.call(data, 'inline_message');
@@ -308,6 +595,7 @@ export class CrossSdkJsAgent {
         };
     }
     async close() {
+        this.resetObservationLedgers();
         try {
             await this.client.close();
         }
@@ -465,6 +753,7 @@ export class CrossSdkJsAgent {
             decrypted,
             encrypted: Boolean(data.e2ee ?? data.encrypted),
             seq: Number(data.seq ?? data.message_seq ?? 0) || 0,
+            need_render: data.need_render !== false,
             ack_seq: Number(data.ack_seq ?? 0) || 0,
             storage: textOf(data.storage),
             volatile_cursor: textOf(data.volatile_cursor),
@@ -489,6 +778,7 @@ export class CrossSdkJsAgent {
             decrypted,
             encrypted: Boolean(data.e2ee ?? data.encrypted),
             seq: Number(data.seq ?? data.message_seq ?? data.msg_seq ?? 0) || 0,
+            need_render: data.need_render !== false,
             error_code: errorCode,
             raw_sha256: sha256Json(data),
             ...envelopeMetadata(data),
@@ -611,6 +901,7 @@ export class CrossSdkJsAgent {
             }
             if (req.method === 'POST' && url.pathname === '/reset') {
                 const body = await readJson(req);
+                this.resetObservationLedgers();
                 const traceId = textOf(body.trace_id ?? '');
                 if (traceId) {
                     this.inbox = this.inbox.filter((item) => item.trace_id !== traceId);
@@ -621,6 +912,7 @@ export class CrossSdkJsAgent {
                 else {
                     this.inbox = [];
                     this.groupInbox = [];
+                    this.peersSnapshots = [];
                     this.traces.clear();
                     this.sendResults.clear();
                 }
@@ -629,11 +921,25 @@ export class CrossSdkJsAgent {
             }
             if (req.method === 'POST' && url.pathname === '/test/raw-push/reset') {
                 const body = await readJson(req);
+                if ((body.pull_barrier_count !== undefined && (typeof body.pull_barrier_count !== 'number' || !Number.isSafeInteger(body.pull_barrier_count) || body.pull_barrier_count < 0)) ||
+                    (body.pull_barrier_scope !== undefined && !['all', 'p2p'].includes(body.pull_barrier_scope)) ||
+                    (body.observation_id !== undefined && typeof body.observation_id !== 'string') ||
+                    (body.release_pull_barrier !== undefined && typeof body.release_pull_barrier !== 'boolean')) {
+                    sendJson(res, 400, { ok: false, error_code: 'bad_request', error_message: 'invalid observation parameters' });
+                    return;
+                }
+                if (body.release_pull_barrier === true) {
+                    this.releasePullBarrier();
+                    sendJson(res, 200, { ok: true, observation_id: this.rawPushObservationId });
+                    return;
+                }
+                this.resetObservationLedgers(body.pull_barrier_count, textOf(body.pull_barrier_scope), body);
                 this.rawPushObservations = [];
                 this.rawPushRpcMethods = [];
                 this.groupChangedEvents = [];
                 this.groupInviteEvents = [];
                 this.readStateEvents = [];
+                this.peersSnapshots = [];
                 this.rawPushObservationId = textOf(body.observation_id ?? '');
                 sendJson(res, 200, { ok: true, observation_id: this.rawPushObservationId });
                 return;
@@ -652,6 +958,11 @@ export class CrossSdkJsAgent {
                 let rpcEntries = [...this.rawPushRpcMethods];
                 let groupChangedEvents = [...this.groupChangedEvents];
                 let groupInviteEvents = [...this.groupInviteEvents];
+                let eventLedger = [...this.eventLedger];
+                let rpcSpans = [...this.rpcSpans];
+                let batchEvents = [...this.batchEvents];
+                if (observationId)
+                    batchEvents = batchEvents.filter((item) => textOf(item.observation_id) === observationId);
                 if (observationId)
                     rpcEntries = rpcEntries.filter((item) => textOf(item.observation_id) === observationId);
                 if (observationId)
@@ -662,17 +973,26 @@ export class CrossSdkJsAgent {
                     groupChangedEvents = groupChangedEvents.filter((item) => textOf(item.group_id) === filters.group_id);
                 if (filters.group_id)
                     groupInviteEvents = groupInviteEvents.filter((item) => textOf(item.group_id) === filters.group_id);
+                for (const key of ['observation_id', 'scope', 'group_id'])
+                    if (filters[key]) {
+                        eventLedger = eventLedger.filter((item) => textOf(item[key]) === filters[key]);
+                        rpcSpans = rpcSpans.filter((item) => textOf(item[key]) === filters[key]);
+                    }
                 rpcEntries = rpcEntries.slice(-limit);
                 const rpcMethods = rpcEntries.map((item) => textOf(item.method));
                 const rpcMethodCounts = {};
                 for (const method of rpcMethods)
                     rpcMethodCounts[method] = Number(rpcMethodCounts[method] ?? 0) + 1;
                 sendJson(res, 200, {
-                    ok: true, items, count: items.length, rpc_methods: rpcMethods, rpc_method_counts: rpcMethodCounts,
+                    ok: true, time_ms: Date.now(), items, count: items.length, rpc_methods: rpcMethods, rpc_method_counts: rpcMethodCounts,
                     rpc_calls: rpcEntries,
                     group_changed_events: groupChangedEvents.slice(-limit),
                     group_invite_events: groupInviteEvents.slice(-limit),
                     read_state_events: this.readStateEvents.slice(-limit),
+                    peers_snapshots: this.peersSnapshots.slice(-limit),
+                    event_ledger: eventLedger, rpc_spans: rpcSpans,
+                    batch_event_mode: this.batchEventMode, batch_events: batchEvents, single_event_counts: this.singleEventCounts,
+                    pull_barrier: { target: this.pullBarrier?.target ?? 0, waiting: this.pullBarrier?.waiting ?? 0, released: this.pullBarrier?.released ?? true, scope: this.pullBarrier?.scope ?? 'all' },
                 });
                 return;
             }
@@ -1693,6 +2013,8 @@ export class CrossSdkJsAgent {
             };
             if (body.ttl !== undefined)
                 params.ttl = Number(body.ttl);
+            if (body.need_render !== undefined)
+                params.need_render = body.need_render;
             const result = await this.client.call('message.send', params);
             const resultObj = jsonObjectOf(result) ?? {};
             const response = {
@@ -1727,6 +2049,10 @@ export class CrossSdkJsAgent {
         const params = {};
         if (seq > 0)
             params.seq = seq;
+        if (textOf(body.sender_aid).trim())
+            params.sender_aid = textOf(body.sender_aid).trim();
+        if (body.cursor_scope !== undefined)
+            params.cursor_scope = body.cursor_scope;
         if (Array.isArray(body.volatile_cursors))
             params.volatile_cursors = body.volatile_cursors;
         else if (textOf(body.volatile_cursor))
@@ -1748,9 +2074,26 @@ export class CrossSdkJsAgent {
     }
     async pull(req, res) {
         const body = await readJson(req);
-        const afterSeq = Number(body.after_seq ?? 0) || 0;
-        const limit = Number(body.limit ?? 50) || 50;
-        const params = { after_seq: afterSeq, limit };
+        if ((body.limit !== undefined && (typeof body.limit !== 'number' || !Number.isSafeInteger(body.limit) || body.limit < 1 || body.limit > 200)) ||
+            (body.max_pages !== undefined && (typeof body.max_pages !== 'number' || !Number.isSafeInteger(body.max_pages) || body.max_pages < 1)) ||
+            (body.after_seq !== undefined && (typeof body.after_seq !== 'number' || !Number.isSafeInteger(body.after_seq) || body.after_seq < 0)) ||
+            ['sender_aid', 'cursor_scope', 'after_volatile_cursor'].some((key) => body[key] !== undefined && typeof body[key] !== 'string') ||
+            (body.force !== undefined && typeof body.force !== 'boolean') ||
+            (body.window_mode !== undefined && !['forward', 'tail'].includes(body.window_mode))) {
+            sendJson(res, 400, { ok: false, error_code: 'bad_request', error_message: 'invalid pull parameters' });
+            return;
+        }
+        const senderAid = textOf(body.sender_aid).trim();
+        const limit = body.limit ?? 50;
+        const params = { limit };
+        if (senderAid)
+            params.sender_aid = senderAid;
+        if (body.after_seq !== undefined)
+            params.after_seq = body.after_seq;
+        for (const key of ['cursor_scope', 'force', 'window_mode', 'max_pages']) {
+            if (body[key] !== undefined)
+                params[key] = body[key];
+        }
         if (textOf(body.after_volatile_cursor))
             params.after_volatile_cursor = textOf(body.after_volatile_cursor);
         try {
@@ -1771,6 +2114,20 @@ export class CrossSdkJsAgent {
     }
     async messageCall(req, res) {
         const body = await readJson(req);
+        if (['start', 'status', 'detach'].includes(textOf(body.action))) {
+            this.messageOperations ??= new Map();
+            const id = textOf(body.operation_id);
+            if (body.action === 'start') {
+                const operation = { ok: true, operation_id: id, status: 'running', started_ms: Date.now() };
+                this.messageOperations.set(id, operation);
+                Promise.resolve().then(() => { operation.entered_ms = Date.now(); return this.client.call(textOf(body.method), (jsonObjectOf(body.params) ?? {})); }).then((result) => Object.assign(operation, { status: 'completed', end_ms: Date.now(), result: jsonSafe(result) }), (error) => Object.assign(operation, { status: 'failed', end_ms: Date.now(), error_code: error instanceof Error ? error.name : 'Error', error_message: error instanceof Error ? error.message : String(error) }));
+            }
+            const operation = this.messageOperations.get(id);
+            if (body.action === 'detach')
+                Object.assign(operation, { detached: true, cancellation: 'application_wait_only', detached_ms: Date.now() });
+            sendJson(res, 200, operation);
+            return;
+        }
         const traceId = textOf(body.trace_id || crypto.randomUUID().replace(/-/g, ''));
         const method = textOf(body.method).trim();
         const params = jsonObjectOf(body.params) ?? {};
@@ -1802,15 +2159,15 @@ export class CrossSdkJsAgent {
             sendJson(res, 500, error);
         }
     }
-    syncNamespace(scope, groupId = '') {
+    syncNamespace(scope, groupId = '', senderAid = '') {
         if (scope === 'p2p')
-            return `p2p:${this.aid}`;
+            return senderAid ? `p2p.peer.v1/${Buffer.from(senderAid, 'utf8').toString('base64url')}` : `p2p:${this.aid}`;
         if (scope === 'group' && groupId)
             return `group:${groupId}`;
         throw new Error('scope must be p2p, or group with group_id');
     }
-    syncStateValue(scope, groupId = '') {
-        const namespace = this.syncNamespace(scope, groupId);
+    syncStateValue(scope, groupId = '', senderAid = '') {
+        const namespace = this.syncNamespace(scope, groupId, senderAid);
         const tracker = this.client._seqTracker;
         if (!tracker)
             throw new Error('SeqTracker is unavailable');
@@ -1819,9 +2176,10 @@ export class CrossSdkJsAgent {
     syncState(url, res) {
         const scope = textOf(url.searchParams.get('scope') || 'p2p').trim().toLowerCase();
         const groupId = textOf(url.searchParams.get('group_id') || '').trim();
+        const senderAid = textOf(url.searchParams.get('sender_aid') || '').trim();
         try {
-            const snapshot = this.syncStateValue(scope, groupId);
-            sendJson(res, 200, { ok: true, scope, ...snapshot });
+            const snapshot = this.syncStateValue(scope, groupId, senderAid);
+            sendJson(res, 200, { ok: true, scope, ...snapshot, peers_snapshots: this.peersSnapshots });
         }
         catch (err) {
             sendJson(res, 400, {
@@ -1841,27 +2199,24 @@ export class CrossSdkJsAgent {
         const body = await readJson(req);
         const scope = textOf(body.scope || 'p2p').trim().toLowerCase();
         const groupId = textOf(body.group_id || '').trim();
+        const senderAid = textOf(body.sender_aid || '').trim();
         const afterSeq = Number(body.after_seq ?? 0) || 0;
         const limit = Number(body.limit ?? 50) || 50;
         try {
-            const params = { after_seq: afterSeq, limit };
-            if (tail)
-                params.window_mode = 'tail';
+            const params = { limit, ...(tail ? { window_mode: 'tail' } : {}) };
+            if (scope === 'group' || body.after_seq !== undefined)
+                params.after_seq = afterSeq;
+            if (scope === 'p2p' && senderAid)
+                params.sender_aid = senderAid;
+            for (const key of ['cursor_scope', 'force', 'max_pages', 'after_volatile_cursor']) {
+                if (body[key] !== undefined)
+                    params[key] = body[key];
+            }
             const method = scope === 'group' ? 'group.pull' : 'message.pull';
             if (scope === 'group')
                 params.group_id = groupId;
-            this.syncNamespace(scope, groupId);
-            let result;
-            if (tail) {
-                result = await this.client.call(method, params);
-            }
-            else {
-                const transport = this.client._transport;
-                if (!transport?.call)
-                    throw new Error('raw transport is unavailable');
-                const wireMethod = scope === 'group' ? 'group.v2.pull' : 'message.v2.pull';
-                result = await transport.call(wireMethod, params);
-            }
+            this.syncNamespace(scope, groupId, senderAid);
+            const result = await this.client.call(method, params);
             const resultObj = jsonObjectOf(result) ?? {};
             const messages = Array.isArray(resultObj.messages) ? resultObj.messages : [];
             if (tail) {
@@ -1872,7 +2227,7 @@ export class CrossSdkJsAgent {
                         await this.storeInboxItem(this.normalizeMessage(msg, true));
                 }
             }
-            const snapshot = this.syncStateValue(scope, groupId);
+            const snapshot = this.syncStateValue(scope, groupId, senderAid);
             sendJson(res, 200, { ok: true, scope, ...snapshot, result: jsonSafe(result) });
         }
         catch (err) {
@@ -1888,6 +2243,7 @@ export class CrossSdkJsAgent {
         const body = await readJson(req);
         const scope = textOf(body.scope || 'p2p').trim().toLowerCase();
         const groupId = textOf(body.group_id || '').trim();
+        const senderAid = textOf(body.sender_aid || '').trim();
         const beforeSeq = Number(body.before_seq ?? 0) || 0;
         const limit = Number(body.limit ?? 50) || 50;
         try {
@@ -1895,9 +2251,13 @@ export class CrossSdkJsAgent {
             const method = scope === 'group' ? 'group.history' : 'message.history';
             if (scope === 'group')
                 params.group_id = groupId;
-            this.syncNamespace(scope, groupId);
+            if (scope === 'p2p' && senderAid)
+                params.sender_aid = senderAid;
+            if (body.cursor_scope !== undefined)
+                params.cursor_scope = body.cursor_scope;
+            this.syncNamespace(scope, groupId, senderAid);
             const result = await this.client.call(method, params);
-            const snapshot = this.syncStateValue(scope, groupId);
+            const snapshot = this.syncStateValue(scope, groupId, senderAid);
             sendJson(res, 200, { ok: true, scope, ...snapshot, result: jsonSafe(result) });
         }
         catch (err) {
@@ -1912,7 +2272,27 @@ export class CrossSdkJsAgent {
     async sessionDisconnect(res) {
         try {
             this.ready = false;
-            await this.client.disconnect();
+            if (!this.pullBarrier?.preserve)
+                this.releasePullBarrier();
+            const barrier = this.pullBarrier;
+            let restore;
+            if (barrier?.preserve && barrier.waiting === 1 && !barrier.released && ['message.pull', 'message.v2.pull'].includes(barrier.heldMethod ?? '')) {
+                const binding = barrier.owner, pipeline = this.client._rpcPipeline;
+                const owners = [...(pipeline?.pullGateStates.values() ?? [])].flatMap((state) => [...state.activeByNamespace.values()])
+                    .filter((job) => job === binding?.job && job.key === binding.key && job.namespace === binding.namespace && job.running && !job.timedOut && !job.invalidated && job.cancel === binding.cancel);
+                if (owners.length !== 1)
+                    throw new Error('保留响应无法定位唯一受跟踪的 pull owner');
+                const owner = owners[0], settled = owner.settled;
+                owner.settled = Promise.resolve();
+                restore = () => { owner.settled = settled; };
+                barrier.span.barrier_owner_isolated = true;
+            }
+            try {
+                await this.client.disconnect();
+            }
+            finally {
+                restore?.();
+            }
             sendJson(res, 200, { ok: true, state: textOf(this.client.state) });
         }
         catch (err) {
@@ -1925,14 +2305,21 @@ export class CrossSdkJsAgent {
     }
     async sessionConnect(req, res) {
         const body = await readJson(req);
+        if (['background_sync', 'inline_realtime_payload_v1', 'batch_events'].some((key) => body[key] !== undefined && typeof body[key] !== 'boolean')) {
+            sendJson(res, 400, { ok: false, error_code: 'bad_request', error_message: 'invalid session parameters' });
+            return;
+        }
         const backgroundSync = body.background_sync === true;
         if (Object.prototype.hasOwnProperty.call(body, 'inline_realtime_payload_v1')) {
             this.inlineRealtimePayloadV1 = body.inline_realtime_payload_v1 !== false;
         }
+        if (typeof body.batch_events === 'boolean')
+            this.batchEventMode = body.batch_events;
+        this.syncBatchEventHandlers();
         try {
             await this.client.connect({ auto_reconnect: false, background_sync: backgroundSync });
             this.ready = true;
-            sendJson(res, 200, { ok: true, background_sync: backgroundSync, inline_realtime_payload_v1: this.inlineRealtimePayloadV1 });
+            sendJson(res, 200, { ok: true, background_sync: backgroundSync, inline_realtime_payload_v1: this.inlineRealtimePayloadV1, batch_events: this.batchEventMode });
         }
         catch (err) {
             sendJson(res, 500, {
@@ -1944,19 +2331,27 @@ export class CrossSdkJsAgent {
     }
     async sessionRestart(req, res) {
         const body = await readJson(req);
+        if (['background_sync', 'inline_realtime_payload_v1', 'batch_events'].some((key) => body[key] !== undefined && typeof body[key] !== 'boolean')) {
+            sendJson(res, 400, { ok: false, error_code: 'bad_request', error_message: 'invalid session parameters' });
+            return;
+        }
         const backgroundSync = body.background_sync === true;
         if (Object.prototype.hasOwnProperty.call(body, 'inline_realtime_payload_v1')) {
             this.inlineRealtimePayloadV1 = body.inline_realtime_payload_v1 !== false;
         }
+        if (typeof body.batch_events === 'boolean')
+            this.batchEventMode = body.batch_events;
+        this.syncBatchEventHandlers();
         this.ready = false;
         try {
+            this.releasePullBarrier();
             await this.client.close();
             this.client = this.newClient();
             this.bindClientEvents();
             await this.ensureConnected(backgroundSync);
             this.startupError = '';
             this.ready = true;
-            sendJson(res, 200, { ok: true, background_sync: backgroundSync, inline_realtime_payload_v1: this.inlineRealtimePayloadV1 });
+            sendJson(res, 200, { ok: true, background_sync: backgroundSync, inline_realtime_payload_v1: this.inlineRealtimePayloadV1, batch_events: this.batchEventMode });
         }
         catch (err) {
             this.startupError = `${err instanceof Error ? err.name : 'Error'}: ${err instanceof Error ? err.message : String(err)}`;
@@ -2070,6 +2465,7 @@ export class CrossSdkJsAgent {
                 payload: { type: 'text', text, trace_id: traceId, case_id: textOf(body.case_id || traceId) },
                 encrypt: e2ee,
                 message_id: messageId,
+                ...(body.need_render !== undefined ? { need_render: body.need_render } : {}),
             });
             const resultObj = jsonObjectOf(result) ?? {};
             const response = {