@agentunion/fastaun 0.5.20 → 0.5.21

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

@@ -14,6 +14,7 @@ import { publicKeyFingerprint } from '../cert-utils.js';
 import { VERSION } from '../version.js';
 import { canonicalJson, digest, buildRequestBinding, verifyMembershipBinding, ProtocolError } from '../org-protocol.js';
 import { ownershipTaskResult } from '../ownership-workflow.js';
+import { TimeoutError } from '../errors.js';
 function envBool(name, fallback = false) {
     const raw = process.env[name];
     if (raw == null)
@@ -128,10 +129,25 @@ export class CrossSdkTsAgent {
     rawPushObservations = [];
     rawPushObservationId = '';
     rawPushRpcMethods = [];
+    eventLedger = [];
+    batchEventMode = false;
+    batchEvents = [];
+    singleEventCounts = { 'message.received': 0, 'group.message_created': 0, 'group.changed': 0 };
+    eventBoundClients = new WeakSet();
+    batchEventClient;
+    batchEventHandlers = [];
+    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();
@@ -154,6 +170,12 @@ export class CrossSdkTsAgent {
         return client;
     }
     bindClientEvents() {
+        this.eventBoundClients ??= new WeakSet();
+        if (this.eventBoundClients.has(this.client)) {
+            this.setBatchEventMode(this.batchEventMode ?? false);
+            return;
+        }
+        this.eventBoundClients.add(this.client);
         this.installTransportRpcObserver();
         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));
@@ -161,22 +183,30 @@ export class CrossSdkTsAgent {
         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.countSingleEvent('message.received');
+            void 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.countSingleEvent('group.message_created');
+            void 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.countSingleEvent('group.changed');
+            void 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.pending', 'ownership.progress', 'ownership.completed', 'ownership.rejected', 'ownership.stopped', 'ownership.error', 'ownership.action_required']) {
             this.client.on(event, (payload) => {
                 this.ownershipEvents.push({ event, payload: jsonSafe(payload) });
@@ -189,15 +219,91 @@ export class CrossSdkTsAgent {
                 this.recordTrace(textOf(payload.org_id), { stage: event, payload });
             });
         }
+        this.setBatchEventMode(this.batchEventMode ?? false);
+    }
+    countSingleEvent(event) {
+        this.singleEventCounts ??= { 'message.received': 0, 'group.message_created': 0, 'group.changed': 0 };
+        this.singleEventCounts[event] = Number(this.singleEventCounts[event] ?? 0) + 1;
+    }
+    async storeApplicationEvent(event, value) {
+        if (event === 'message.received') {
+            this.storeEventLedger(event, value);
+            await this.storeInboxItem(this.normalizeMessage(value, true));
+        }
+        else if (event === 'group.message_created') {
+            this.storeEventLedger(event, value);
+            await this.storeGroupInboxItem(this.normalizeGroupMessage(value, true));
+        }
+        else if (event === 'group.changed')
+            this.storeGroupChangedPublicEvent(value);
+    }
+    setBatchEventMode(enabled) {
+        this.batchEventMode = enabled;
+        if (enabled && this.batchEventClient === this.client && this.batchEventHandlers?.length)
+            return;
+        for (const { event, handler } of this.batchEventHandlers ?? [])
+            this.batchEventClient?.off(event, handler);
+        this.batchEventClient = this.client;
+        this.batchEventHandlers = [];
+        if (!enabled)
+            return;
+        for (const event of ['message.batch', 'group.message_batch', 'group.event_batch']) {
+            const handler = async (value) => {
+                const data = jsonObjectOf(value) ?? {};
+                const items = JSON.parse(JSON.stringify(jsonSafe(Array.isArray(data.items) ? data.items : [])));
+                this.batchEvents ??= [];
+                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)
+                    await this.storeApplicationEvent(textOf(item.event), item.payload);
+            };
+            this.batchEventHandlers.push({ event, handler });
+            this.client.on(event, handler);
+        }
     }
     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();
+                try {
+                    await originalClose.call(transport);
+                }
+                finally {
+                    if (!this.pullBarrier?.preserve)
+                        this.releasePullBarrier();
+                }
+            };
+        transport.call = (method, params, timeout, trace, background) => {
             this.storeRawPushRpcMethod({ type: 'rpc', method, request_window: this.rawPushRequestWindow(params) });
             let requestParams = params;
             if (method === 'auth.connect' && !this.inlineRealtimePayloadV1 && jsonObjectOf(params)) {
@@ -209,8 +315,219 @@ export class CrossSdkTsAgent {
                 }
                 requestParams = request;
             }
-            return await originalCall.call(transport, method, requestParams, timeout, trace, background);
+            const generation = this.observationGeneration;
+            const span = this.startRpcSpan(method, requestParams);
+            const controller = new AbortController();
+            let request;
+            const observed = {};
+            const pending = (async () => {
+                try {
+                    request = originalCall.call(transport, method, requestParams, timeout, trace, background);
+                    const result = await request;
+                    if (span) {
+                        this.finishRpcResponse(span, result);
+                        if (generation === this.observationGeneration && (this.isObservedPull(method) || this.pullBarrier?.method === method)) {
+                            await this.waitForPullBarrier(method, controller.signal, timeout ?? transport._timeout ?? 35_000, span, observed.owner);
+                        }
+                        if (generation === this.observationGeneration)
+                            this.injectRPCFailure(method, span);
+                        span.success = true;
+                    }
+                    return result;
+                }
+                catch (error) {
+                    if (span) {
+                        span.success = false;
+                        span.error = error instanceof Error ? error.name : String(error);
+                    }
+                    throw error;
+                }
+                finally {
+                    if (span)
+                        span.end_ms = Date.now();
+                }
+            })();
+            pending.cancel = () => { controller.abort(); request?.cancel?.(); };
+            this.rpcObservedPulls.set(pending, observed);
+            return pending;
+        };
+    }
+    storeEventLedger(event, 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, event, event_index: this.eventLedger.length + 1, time_ms: Date.now(),
+            scope: event === 'message.received' ? 'p2p' : 'group', receiver_aid: this.aid,
+            device_id: textOf(internal._deviceId), slot_id: textOf(internal._slotId ?? this.slotId),
+            sender_aid: textOf(data.sender_aid ?? data.from_aid ?? data.from), 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 } : {}),
+        });
+    }
+    isObservedPull(method) {
+        return ['message.pull', 'message.v2.pull', 'group.pull', 'group.v2.pull', 'group.pull_messages', 'group.pull_events', 'group.events'].includes(method);
+    }
+    startRpcSpan(method, value) {
+        if (!this.isObservedPull(method) && !['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), groupId = textOf(params.group_id ?? params.group_aid);
+        const namespace = method === 'message.peers' ? '' : method.startsWith('group.')
+            ? groupId ? `${method === 'group.pull_events' || method === 'group.events' || method === 'group.ack_events' ? 'group_event' : 'group'}:${groupId}` : ''
+            : senderAid ? `p2p.peer.v1/${Buffer.from(senderAid, 'utf8').toString('base64url')}` : `p2p:${this.aid}`;
+        const span = {
+            observation_id: this.rawPushObservationId, span_id: crypto.randomUUID(), boundary: 'transport_call', method,
+            start_ms: Date.now(), response_ms: null, end_ms: null, success: null,
+            cursor_scope: textOf(params.cursor_scope) || (method === 'message.peers' || senderAid ? 'peer' : method.startsWith('group.') ? namespace.startsWith('group_event:') ? 'group_event' : 'group' : 'global'), sender_aid: senderAid,
+            group_id: groupId, namespace, request_window: this.observedRequestWindow(params),
+            response_message_count: 0, response_volatile_count: 0, response_event_count: 0,
+            response_item_keys: [], response_event_keys: [],
+            has_more: null, persistent_has_more: null, volatile_has_more: null, has_more_persistent: null, has_more_volatile: null, effective_ack_seq: null,
         };
+        this.rpcSpans.push(span);
+        return span;
+    }
+    observedRequestWindow(params) {
+        const window = {};
+        for (const key of ['after_seq', 'before_seq', 'until_seq', 'after_message_seq', 'after_event_seq', 'up_to_seq', 'seq', 'ack_seq', 'msg_seq', 'event_seq', 'limit', 'max_pages']) {
+            if (typeof params[key] === 'number' && Number.isSafeInteger(params[key]))
+                window[key] = params[key];
+        }
+        for (const key of ['window_mode', 'cursor_scope', 'sender_aid', 'group_id', 'group_aid', 'device_id', 'slot_id', 'after_volatile_cursor', 'mode', 'after_sender_aid']) {
+            if (typeof params[key] === 'string')
+                window[key] = params[key];
+        }
+        for (const key of ['force', 'pending_only'])
+            if (typeof params[key] === 'boolean')
+                window[key] = params[key];
+        for (const key of ['volatile_cursors', 'volatile_ids']) {
+            if (Array.isArray(params[key]))
+                window[key] = params[key].filter((item) => typeof item === 'string');
+        }
+        return window;
+    }
+    finishRpcResponse(span, value) {
+        const response = jsonObjectOf(value) ?? {};
+        const messages = Array.isArray(response.messages) ? response.messages : [];
+        span.response_ms = Date.now();
+        span.response_message_count = messages.length;
+        span.response_volatile_count = messages.filter((item) => jsonObjectOf(item)?.storage === 'volatile').length;
+        span.response_event_count = Array.isArray(response.events) ? response.events.length : 0;
+        const sequenceOf = (raw, ...keys) => {
+            for (const key of keys) {
+                const value = raw[key];
+                if (typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value))
+                    return value;
+            }
+            return 0;
+        };
+        const itemKeys = new Map();
+        for (const key of ['messages', 'volatile_messages', 'volatile']) {
+            for (const item of Array.isArray(response[key]) ? response[key] : []) {
+                const raw = jsonObjectOf(item) ?? {}, cursor = textOf(raw.volatile_cursor);
+                const identity = { message_id: textOf(raw.message_id ?? raw.id),
+                    seq: sequenceOf(raw, 'seq', 'message_seq', 'msg_seq'),
+                    storage: typeof raw.storage === 'string' ? raw.storage : cursor ? 'volatile' : 'persistent', volatile_cursor: cursor };
+                itemKeys.set(JSON.stringify(identity), identity);
+            }
+        }
+        span.response_item_keys = [...itemKeys.values()];
+        span.response_event_keys = (Array.isArray(response.events) ? response.events : []).map((item) => {
+            const raw = jsonObjectOf(item) ?? {};
+            return { event_id: textOf(raw.event_id), event_seq: sequenceOf(raw, 'event_seq', 'seq') };
+        });
+        span.has_more = typeof response.has_more === 'boolean' ? response.has_more : null;
+        span.has_more_persistent = typeof response.persistent_has_more === 'boolean' ? response.persistent_has_more : null;
+        span.has_more_volatile = typeof response.volatile_has_more === 'boolean' ? response.volatile_has_more : null;
+        span.persistent_has_more = span.has_more_persistent;
+        span.volatile_has_more = span.has_more_volatile;
+        for (const key of ['peer_ack_seq', 'effective_ack_seq', 'server_ack_seq', 'ack_seq', 'up_to_seq', 'acked_seq']) {
+            if (typeof response[key] === 'number' && Number.isSafeInteger(response[key]))
+                span[key] = response[key];
+        }
+        const effective = response.peer_ack_seq ?? response.effective_ack_seq ?? response.ack_seq ?? response.up_to_seq ?? response.acked_seq;
+        if (typeof effective === 'number' && Number.isSafeInteger(effective))
+            span.effective_ack_seq = effective;
+        const volatileAck = jsonObjectOf(response.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() {
+        const barrier = this.pullBarrier;
+        if (!barrier || barrier.released)
+            return;
+        barrier.released = true;
+        barrier.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(pullBarrierCount = 0, scope = 'all', controls = {}) {
+        this.releasePullBarrier();
+        this.observationGeneration = (this.observationGeneration ?? 0) + 1;
+        this.eventLedger = [];
+        this.batchEvents = [];
+        this.singleEventCounts = { 'message.received': 0, 'group.message_created': 0, 'group.changed': 0 };
+        this.rpcSpans = [];
+        this.rpcFailures = Array.isArray(controls.rpc_failures) ? controls.rpc_failures.map((item) => ({ ...jsonObjectOf(item) })) : [];
+        this.pullBarrier = null;
+        if (Number.isSafeInteger(pullBarrierCount) && pullBarrierCount > 0) {
+            let release;
+            const promise = new Promise((resolve) => { release = resolve; });
+            this.pullBarrier = { target: pullBarrierCount, scope: scope === 'p2p' ? 'p2p' : 'all', admitted: 0, waiting: 0, released: false, promise, release,
+                sender: textOf(controls.pull_barrier_sender_aid), method: textOf(controls.pull_barrier_method), preserve: controls.preserve_pull_barrier === true };
+        }
+    }
+    async waitForPullBarrier(method, signal, timeout, span, owner) {
+        const barrier = this.pullBarrier;
+        if (!barrier || barrier.released || barrier.admitted >= barrier.target)
+            return;
+        if (barrier.scope === 'p2p' && method !== 'message.pull' && method !== 'message.v2.pull' && barrier.method !== method)
+            return;
+        if ((barrier.sender && barrier.sender !== span.sender_aid) || (barrier.method && barrier.method !== method))
+            return;
+        barrier.admitted += 1;
+        barrier.waiting += 1;
+        if (barrier.preserve) {
+            barrier.heldMethod = method;
+            barrier.owner = owner;
+            barrier.span = span;
+        }
+        let timer;
+        let abort;
+        try {
+            await Promise.race([barrier.promise, new Promise((_resolve, reject) => {
+                    abort = () => reject(new Error('pull observation barrier cancelled'));
+                    if (!barrier.preserve)
+                        signal.addEventListener('abort', abort, { once: true });
+                    if (signal.aborted && !barrier.preserve)
+                        abort();
+                    timer = setTimeout(() => reject(new Error('pull observation barrier timeout')), Math.max(1, timeout));
+                })]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            barrier.waiting -= 1;
+        }
     }
     storeRawPushObservation(rawEvent, scope, defaultKind, value) {
         const data = jsonObjectOf(value) ?? {};
@@ -299,6 +616,7 @@ export class CrossSdkTsAgent {
         };
     }
     async close() {
+        this.resetObservationLedgers();
         try {
             await this.client.close();
         }
@@ -489,6 +807,7 @@ export class CrossSdkTsAgent {
             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),
@@ -514,6 +833,7 @@ export class CrossSdkTsAgent {
             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),
             ...metadata,
@@ -543,6 +863,7 @@ export class CrossSdkTsAgent {
             }
             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);
@@ -553,6 +874,7 @@ export class CrossSdkTsAgent {
                 else {
                     this.inbox = [];
                     this.groupInbox = [];
+                    this.peersSnapshots = [];
                     this.traces.clear();
                     this.sendResults.clear();
                 }
@@ -561,11 +883,25 @@ export class CrossSdkTsAgent {
             }
             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;
@@ -584,6 +920,23 @@ export class CrossSdkTsAgent {
                 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)
+                    eventLedger = eventLedger.filter((item) => textOf(item.observation_id) === observationId);
+                if (observationId)
+                    rpcSpans = rpcSpans.filter((item) => textOf(item.observation_id) === observationId);
+                if (filters.scope)
+                    eventLedger = eventLedger.filter((item) => textOf(item.scope) === filters.scope);
+                if (filters.scope)
+                    rpcSpans = rpcSpans.filter((item) => textOf(item.method).startsWith(filters.scope === 'p2p' ? 'message.' : 'group.'));
+                if (filters.group_id)
+                    eventLedger = eventLedger.filter((item) => textOf(item.group_id) === filters.group_id);
+                if (filters.group_id)
+                    rpcSpans = rpcSpans.filter((item) => textOf(item.group_id) === filters.group_id);
                 if (observationId)
                     rpcEntries = rpcEntries.filter((item) => textOf(item.observation_id) === observationId);
                 if (observationId)
@@ -600,11 +953,18 @@ export class CrossSdkTsAgent {
                 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 ?? false,
+                    batch_events: batchEvents,
+                    single_event_counts: this.singleEventCounts ?? { 'message.received': 0, 'group.message_created': 0, 'group.changed': 0 },
+                    pull_barrier: { target: this.pullBarrier?.target ?? 0, waiting: this.pullBarrier?.waiting ?? 0, released: this.pullBarrier?.released ?? true, scope: this.pullBarrier?.scope ?? 'all' },
                 });
                 return;
             }
@@ -896,6 +1256,8 @@ export class CrossSdkTsAgent {
         };
         if (body.ttl !== undefined)
             params.ttl = Number(body.ttl);
+        if (body.need_render !== undefined)
+            params.need_render = body.need_render;
         try {
             const result = await this.client.call('message.send', params);
             const resultObj = result && typeof result === 'object' ? result : {};
@@ -931,6 +1293,10 @@ export class CrossSdkTsAgent {
         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))
@@ -952,9 +1318,26 @@ export class CrossSdkTsAgent {
     }
     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 {
@@ -976,6 +1359,20 @@ export class CrossSdkTsAgent {
     }
     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) ?? {};
@@ -1007,15 +1404,15 @@ export class CrossSdkTsAgent {
             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');
@@ -1024,9 +1421,10 @@ export class CrossSdkTsAgent {
     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, {
@@ -1046,27 +1444,24 @@ export class CrossSdkTsAgent {
         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, window_mode: tail ? 'tail' : 'forward' };
+            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) {
@@ -1077,7 +1472,7 @@ export class CrossSdkTsAgent {
                         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) {
@@ -1093,6 +1488,7 @@ export class CrossSdkTsAgent {
         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 {
@@ -1100,9 +1496,13 @@ export class CrossSdkTsAgent {
             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) {
@@ -1117,7 +1517,25 @@ export class CrossSdkTsAgent {
     async sessionDisconnect(res) {
         try {
             this.ready = false;
-            await this.client.disconnect();
+            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) {
@@ -1130,14 +1548,19 @@ export class CrossSdkTsAgent {
     }
     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;
         }
         try {
+            this.setBatchEventMode(typeof body.batch_events === 'boolean' ? body.batch_events : this.batchEventMode ?? false);
             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, {
@@ -1149,19 +1572,25 @@ export class CrossSdkTsAgent {
     }
     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;
         }
         this.ready = false;
         try {
+            if (typeof body.batch_events === 'boolean')
+                this.batchEventMode = body.batch_events;
             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)}`;
@@ -2053,6 +2482,7 @@ export class CrossSdkTsAgent {
                 payload,
                 encrypt: e2ee,
                 message_id: messageId,
+                ...(body.need_render !== undefined ? { need_render: body.need_render } : {}),
             });
             const resultObj = result && typeof result === 'object' && !Array.isArray(result) ? result : {};
             const response = {