@agentunion/fastaun 0.5.20 → 0.5.22

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

@@ -5,6 +5,7 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { tmpdir } from 'node:os';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { URL } from 'node:url';
 import { fileURLToPath } from 'node:url';
 import { AUNClient } from '../client.js';
@@ -14,6 +15,33 @@ 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';
+const credentialProcessStartupId = crypto.randomUUID();
+const cacheReadContext = new AsyncLocalStorage();
+const cacheReadObservers = new WeakMap();
+function acquireCacheReadObserver(target, key, wrap) {
+    let observers = cacheReadObservers.get(target);
+    if (!observers) {
+        observers = new Map();
+        cacheReadObservers.set(target, observers);
+    }
+    let observer = observers.get(key);
+    if (!observer) {
+        const original = target[key];
+        target[key] = wrap(original);
+        observer = { users: 0, restore: () => { target[key] = original; } };
+        observers.set(key, observer);
+    }
+    observer.users += 1;
+    return () => {
+        if (--observer.users === 0) {
+            observer.restore();
+            observers.delete(key);
+            if (!observers.size)
+                cacheReadObservers.delete(target);
+        }
+    };
+}
 function envBool(name, fallback = false) {
     const raw = process.env[name];
     if (raw == null)
@@ -128,10 +156,32 @@ 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 = [];
+    p2pSubscription = true;
+    p2pEventClient;
+    p2pEventHandler;
+    p2pDeliveryPaused = false;
+    p2pDeliveryBlocked = 0;
+    p2pDeliveryGate = null;
+    p2pDeliveryRetiredClients = new WeakSet();
+    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();
@@ -139,6 +189,18 @@ export class CrossSdkTsAgent {
     constructor() {
         this.client = this.newClient();
     }
+    credentialStartup;
+    credentialProcessId = credentialProcessStartupId;
+    credentialProcessCheckpoint() {
+        const internal = this.client;
+        const metadata = internal._tokenStore._loadMetadataStrict(this.aid) ?? {};
+        return structuredClone({ pid: process.pid, startup_uuid: this.credentialProcessId, aid: this.aid,
+            cert_fingerprint: this.client.currentAid?.certFingerprint, store: this.aunPath,
+            records: metadata.credential_renewals_v1 ?? {}, revocations: metadata.credential_revocations_v1 ?? { version: 1, authorities: {} } });
+    }
+    captureCredentialStartup() {
+        this.credentialStartup ??= { ...this.credentialProcessCheckpoint(), phase: 'before_connect' };
+    }
     async start() {
         this.bindClientEvents();
         // Cross-SDK runner 需要先由显式 Tail 建立窗口证明；启动阶段不得遗留后台 Pull。
@@ -154,29 +216,39 @@ export class CrossSdkTsAgent {
         return client;
     }
     bindClientEvents() {
+        this.eventBoundClients ??= new WeakSet();
+        if (this.eventBoundClients.has(this.client)) {
+            this.setP2pSubscription(this.p2pSubscription ?? true);
+            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));
         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.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 +261,151 @@ export class CrossSdkTsAgent {
                 this.recordTrace(textOf(payload.org_id), { stage: event, payload });
             });
         }
+        this.setP2pSubscription(this.p2pSubscription ?? true);
+    }
+    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);
+    }
+    setP2pSubscription(enabled) {
+        this.p2pSubscription = enabled;
+        if (this.p2pEventHandler && (this.p2pEventClient !== this.client || !enabled)) {
+            this.p2pEventClient?.off('message.received', this.p2pEventHandler);
+            this.p2pEventHandler = undefined;
+        }
+        this.p2pEventClient = this.client;
+        if (enabled && !this.p2pEventHandler) {
+            const client = this.client;
+            this.p2pEventHandler = async (msg) => {
+                if ((this.p2pDeliveryPaused || this.p2pDeliveryRetiredClients?.has(client)) && !await this.waitForP2pDelivery(client))
+                    return;
+                this.countSingleEvent('message.received');
+                await this.storeApplicationEvent('message.received', msg);
+            };
+            this.client.on('message.received', this.p2pEventHandler);
+        }
+        this.setBatchEventMode(this.batchEventMode ?? false);
+    }
+    setP2pDeliveryPaused(paused) {
+        this.p2pDeliveryPaused = paused;
+        if (!paused) {
+            const gate = this.p2pDeliveryGate;
+            this.p2pDeliveryGate = null;
+            gate?.release();
+        }
+    }
+    async waitForP2pDelivery(client) {
+        if (this.p2pDeliveryRetiredClients?.has(client))
+            return false;
+        this.p2pDeliveryBlocked = (this.p2pDeliveryBlocked ?? 0) + 1;
+        try {
+            while (this.p2pDeliveryPaused && !this.p2pDeliveryRetiredClients?.has(client)) {
+                if (!this.p2pDeliveryGate) {
+                    let release;
+                    const promise = new Promise((resolve) => { release = resolve; });
+                    this.p2pDeliveryGate = { promise, release };
+                }
+                await this.p2pDeliveryGate.promise;
+            }
+            return !this.p2pDeliveryRetiredClients?.has(client);
+        }
+        finally {
+            this.p2pDeliveryBlocked -= 1;
+        }
+    }
+    retireP2pDelivery(client) {
+        this.p2pDeliveryRetiredClients ??= new WeakSet();
+        this.p2pDeliveryRetiredClients.add(client);
+        const gate = this.p2pDeliveryGate;
+        this.p2pDeliveryGate = null;
+        gate?.release();
+    }
+    applicationDeliveryState() {
+        const dispatcher = this.client._dispatcher;
+        return { subscribed: this.p2pSubscription ?? true, paused: this.p2pDeliveryPaused ?? false, blocked: this.p2pDeliveryBlocked ?? 0,
+            capacity: dispatcher?._messageQueueCapacity?.() ?? 0, used: dispatcher?._queuedMessageCount ?? 0, waiting: dispatcher?._messageAdmissionWaiters ?? 0 };
+    }
+    setBatchEventMode(enabled) {
+        this.batchEventMode = enabled;
+        const events = enabled ? ['message.batch', 'group.message_batch', 'group.event_batch'].filter((event) => event !== 'message.batch' || this.p2pSubscription !== false) : [];
+        if (this.batchEventClient === this.client && this.batchEventHandlers?.length === events.length && this.batchEventHandlers.every((item, index) => item.event === events[index]))
+            return;
+        for (const { event, handler } of this.batchEventHandlers ?? [])
+            this.batchEventClient?.off(event, handler);
+        this.batchEventClient = this.client;
+        this.batchEventHandlers = [];
+        const client = this.client;
+        for (const event of events) {
+            const handler = async (value) => {
+                if (event === 'message.batch' && (this.p2pDeliveryPaused || this.p2pDeliveryRetiredClients?.has(client)) && !await this.waitForP2pDelivery(client))
+                    return;
+                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,9 +417,220 @@ 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) ?? {};
         const hasInline = Object.prototype.hasOwnProperty.call(data, 'inline_message');
@@ -299,6 +718,8 @@ export class CrossSdkTsAgent {
         };
     }
     async close() {
+        this.resetObservationLedgers();
+        this.retireP2pDelivery(this.client);
         try {
             await this.client.close();
         }
@@ -310,7 +731,7 @@ export class CrossSdkTsAgent {
         const internal = this.client;
         const store = new AIDStore({
             aunPath: this.aunPath,
-            encryptionSeed: '',
+            encryptionSeed: process.env.AUN_TEST_ENCRYPTION_SEED || process.env.AUN_ENCRYPTION_SEED || '',
             slotId: this.slotId,
             debug: this.debug,
         });
@@ -343,6 +764,7 @@ export class CrossSdkTsAgent {
             throw new Error(`load identity failed: ${loaded.error.code}: ${loaded.error.message}`);
         }
         this.client.loadIdentity(loaded.data.aid);
+        this.captureCredentialStartup();
         const checked = await store.checkAgentMd(this.aid);
         const localEtag = checked.ok ? String(checked.data.local_etag ?? '').trim() : '';
         const remoteEtag = checked.ok ? String(checked.data.remote_etag ?? '').trim() : '';
@@ -489,6 +911,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 +937,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 +967,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 +978,7 @@ export class CrossSdkTsAgent {
                 else {
                     this.inbox = [];
                     this.groupInbox = [];
+                    this.peersSnapshots = [];
                     this.traces.clear();
                     this.sendResults.clear();
                 }
@@ -561,11 +987,38 @@ 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') ||
+                    ['p2p_subscription', 'p2p_delivery_paused', 'preserve_observations'].some((key) => body[key] !== undefined && typeof body[key] !== 'boolean')) {
+                    sendJson(res, 400, { ok: false, error_code: 'bad_request', error_message: 'invalid observation parameters' });
+                    return;
+                }
+                if (typeof body.p2p_subscription === 'boolean')
+                    this.setP2pSubscription(body.p2p_subscription);
+                const p2pPullSpanIds = body.preserve_observations === true && body.p2p_subscription === false
+                    ? this.rpcSpans.filter((span) => span.method === 'message.pull' || span.method === 'message.v2.pull').map((span) => textOf(span.span_id)) : undefined;
+                if (typeof body.p2p_delivery_paused === 'boolean')
+                    this.setP2pDeliveryPaused(body.p2p_delivery_paused);
+                if (body.preserve_observations === true) {
+                    if (body.release_pull_barrier === true)
+                        this.releasePullBarrier();
+                    sendJson(res, 200, { ok: true, observation_id: this.rawPushObservationId, ...(p2pPullSpanIds !== undefined ? { p2p_pull_span_ids: p2pPullSpanIds } : {}) });
+                    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 +1037,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 +1070,20 @@ 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,
+                    observation_id: this.rawPushObservationId,
                     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 },
+                    application_delivery: this.applicationDeliveryState(),
+                    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 +1375,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 +1412,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 +1437,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 +1478,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 +1523,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 +1540,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 +1563,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 +1591,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 +1607,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 +1615,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 +1636,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 +1667,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 +1691,26 @@ 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;
+            this.retireP2pDelivery(this.client);
             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)}`;
@@ -1231,15 +1780,36 @@ export class CrossSdkTsAgent {
         const now = Math.floor(Date.now() / 1000);
         if (op === 'request')
             return buildRequestBinding(textOf(params.method), textOf(params.target), params.params, textOf(params.credential_cid), textOf(params.nonce), textOf(params.request_id), now, now + 300);
-        if (['register', 'sign', 'certificate', 'create', 'prepare'].includes(op)) {
+        if (op === 'revocation_checkpoint') {
+            const internal = this.client;
+            if (params.sync === true)
+                await internal._getCredentialRenewal()._syncRevocations();
+            return internal._tokenStore._loadMetadataStrict(this.aid)?.credential_revocations_v1 ?? { version: 1, authorities: {} };
+        }
+        if (op === 'credential_process')
+            return params.startup === true ? this.credentialStartup : this.credentialProcessCheckpoint();
+        if (op === 'manage_credential') {
+            const manager = this.client._getCredentialRenewal();
+            await manager.serial(() => manager.rememberNow(params.credential, {}, this.aid, undefined, true));
+            return await this.client.credential.current(textOf(params.credential.cid));
+        }
+        if (op === 'current_credential')
+            return await this.client.credential.current(textOf(params.credential_cid));
+        if (['register', 'sign', 'certificate', 'local_certificate', 'create', 'prepare', 'transfer_accept', 'renew'].includes(op)) {
             const store = this.aidStore();
             try {
-                if (op === 'prepare') {
+                if (op === 'transfer_accept')
+                    return await this.client.org.lifecycle.transferAccept({ ...jsonObjectOf(params.params), aidStore: store });
+                if (op === 'prepare' || op === 'renew') {
                     const request = jsonObjectOf(params.params) ?? {};
                     const orgId = textOf(params.org_id ?? request.org_id);
                     const loaded = orgId ? store.load(orgId) : null;
                     const orgSigner = loaded?.ok && loaded.data.aid.isPrivateKeyValid() ? loaded.data.aid : undefined;
-                    return this.client.org.prepareRequest(textOf(params.method), request, textOf(params.target), this.client.currentAid, { ...jsonObjectOf(params.options), orgSigner });
+                    const credentialOptions = jsonObjectOf(params.credential_options);
+                    if (op === 'prepare')
+                        return this.client.org.prepareRequest(textOf(params.method), request, textOf(params.target), this.client.currentAid, { ...jsonObjectOf(params.options), orgSigner, ...(credentialOptions ? { credentialOptions } : {}) });
+                    const prepared = this.client.org.prepareRequest('org.member.renewCredential', request, textOf(params.target) || `org.${orgId.slice(orgId.indexOf('.') + 1)}`, this.client.currentAid, { orgSigner, credentialOptions: jsonObjectOf(params.credential_options) ?? undefined });
+                    return { result: await this.client.org.member.renewCredential(prepared), params: prepared };
                 }
                 if (op === 'register') {
                     const registered = await store.register(textOf(params.org_id), { type: 'org', owner: this.aid, exttype: 'company' });
@@ -1248,12 +1818,14 @@ export class CrossSdkTsAgent {
                 }
                 const loaded = op === 'certificate'
                     ? await store.resolve(textOf(params.as_aid), { skipAgentMd: true })
-                    : (params.as_aid || params.org_id) ? store.load(textOf(params.as_aid ?? params.org_id)) : null;
+                    : (params.as_aid || op === 'local_certificate' || params.org_id) ? store.load(textOf(params.as_aid ?? params.org_id)) : null;
                 if (loaded && !loaded.ok)
                     throw new Error(String(loaded.error));
                 const identity = loaded?.data?.aid ?? this.client.currentAid;
                 const result = { cert_fingerprint: identity.certFingerprint, certificate: identity.certPem };
-                if (op === 'sign') {
+                if (op === 'local_certificate')
+                    result.has_private_key = identity.isPrivateKeyValid();
+                else if (op === 'sign') {
                     const signed = await identity.sign(Buffer.from(canonicalJson(params.payload)));
                     if (!signed.ok)
                         throw new Error(String(signed.error));
@@ -1281,6 +1853,7 @@ export class CrossSdkTsAgent {
                     const actual = jsonObjectOf(params.context) ?? params;
                     const memberships = jsonObjectOf(params.memberships) ?? {};
                     result.verification = { ...this.client.credential.verify(value, { resolveCertificate: resolver, resolveActorCertificate: resolver,
+                            resolveStatusProof: (cid) => params.status_proofs?.[cid],
                             resolveStatus: (cid) => params.statuses?.[cid], now: verificationNow, audience: textOf(actual.audience), subject: textOf(actual.subject) || undefined,
                             ns: textOf(actual.ns), action: textOf(actual.action), resource: textOf(actual.resource), rootIssuer: textOf(actual.root_issuer) || undefined,
                             params: jsonObjectOf(actual.params) ?? {}, units: jsonObjectOf(actual.units) ?? {}, clientIp: textOf(actual.client_ip), method: textOf(actual.method), target: textOf(actual.target),
@@ -1322,6 +1895,18 @@ export class CrossSdkTsAgent {
                 case 'sdk.org.protocol':
                     result = await this.orgProtocol(params);
                     break;
+                case 'credential.register':
+                    result = await this.client.credential.register(params);
+                    break;
+                case 'credential.status':
+                    result = await this.client.credential.status(params);
+                    break;
+                case 'credential.revoke':
+                    result = await this.client.credential.revoke(params);
+                    break;
+                case 'credential.revocationList':
+                    result = await this.client.credential.revocationList(params);
+                    break;
                 case 'org.lifecycle.create':
                     result = await this.client.org.lifecycle.create(params);
                     break;
@@ -1414,6 +1999,10 @@ export class CrossSdkTsAgent {
                 error_code: err instanceof Error ? err.name : 'Error',
                 error_message: err instanceof Error ? err.message : String(err),
             };
+            if (method.startsWith('org.') || method === 'sdk.org.protocol') {
+                const remote = err;
+                error.rpc_error_code = remote?.stringCode || remote?.data?.error_code || remote?.data?.code || (typeof remote?.code === 'string' ? remote.code : '');
+            }
             this.recordTrace(traceId, { stage: 'group_call_error', method, error });
             sendJson(res, 500, error);
         }
@@ -1578,6 +2167,8 @@ export class CrossSdkTsAgent {
         }
     }
     async callGroupFsAction(action, params, asGroupAid = '') {
+        if (action === 'cache_read')
+            return await this.cacheRead(params, true, asGroupAid);
         const groupFs = this.client.group.fs;
         let signingStore = null;
         const withSigning = (source) => {
@@ -1717,7 +2308,124 @@ export class CrossSdkTsAgent {
         }
         return response;
     }
+    async cacheRead(params, group = false, asGroupAid = '') {
+        const operation = textOf(params.operation || 'read_bytes');
+        if (!['read_bytes', 'stat', 'lstat', 'list', 'ls', 'find', 'du', 'df'].includes(operation)) {
+            throw new Error(`unsupported cache read operation: ${operation}`);
+        }
+        const transport = this.client._transport;
+        const lowlevel = group ? this.client.group.fs.lowlevel : this.client.storage.lowlevel;
+        const counters = { rpc_count: 0, http_count: 0, body_transfers: 0, body_bytes: 0, methods: {}, wire_params: [] };
+        const releaseCall = acquireCacheReadObserver(transport, 'call', (originalCall) => (method, request, ...tail) => {
+            const context = cacheReadContext.getStore();
+            const counted = context && (method.startsWith('storage.') || method.startsWith('group.fs.'));
+            if (counted) {
+                context.rpc_count += 1;
+                context.methods[method] = (context.methods[method] || 0) + 1;
+                context.wire_params.push({ method, params: JSON.parse(JSON.stringify(request ?? {})) });
+            }
+            const pending = originalCall.call(transport, method, request, ...tail);
+            const observed = pending.then((result) => {
+                const payload = jsonObjectOf(result);
+                const content = payload?.content_base64 ?? payload?.content;
+                if (counted && !payload?.not_modified && typeof content === 'string') {
+                    context.body_transfers += 1;
+                    context.body_bytes += Buffer.from(content, 'base64').byteLength;
+                }
+                return result;
+            });
+            if (pending.cancel)
+                observed.cancel = () => pending.cancel();
+            return observed;
+        });
+        const releaseHttp = acquireCacheReadObserver(lowlevel, 'httpGet', (originalHttp) => async (...args) => {
+            const context = cacheReadContext.getStore();
+            if (context)
+                context.http_count += 1;
+            const data = await originalHttp.call(lowlevel, ...args);
+            if (context) {
+                context.body_transfers += 1;
+                context.body_bytes += data.byteLength;
+            }
+            return data;
+        });
+        const readOnce = async () => {
+            const remotePath = textOf(params.path);
+            const noCache = Boolean(params.no_cache ?? params.noCache);
+            if (group) {
+                const options = withoutKeys(params, ['operation', 'count', 'concurrent', 'no_cache']);
+                options.noCache = noCache;
+                if (operation !== 'read_bytes')
+                    return await this.callGroupFsAction(operation === 'list' ? 'ls' : operation, options, asGroupAid);
+                delete options.path;
+                const dst = this.writeTempText('', '.bin');
+                try {
+                    const result = await this.callGroupFsAction('cp', { ...options, src: remotePath, dst, force: true }, asGroupAid);
+                    const response = jsonObjectOf(result);
+                    return { content_base64: response.content_base64, size_bytes: response.size_bytes };
+                }
+                finally {
+                    fs.rmSync(dst, { force: true });
+                }
+            }
+            const storage = this.client.storage;
+            const options = {
+                owner: textOf(params.owner_aid ?? params.ownerAID).trim() || undefined,
+                bucket: textOf(params.bucket).trim() || 'default', noCache,
+            };
+            if (operation !== 'df')
+                options.token = textOf(params.token).trim() || undefined;
+            if (operation === 'read_bytes') {
+                const shareId = textOf(params.share_id ?? params.shareId).trim();
+                if (shareId) {
+                    const result = await storage.lowlevel.getByShare({ shareId, noCache });
+                    const data = result.download_url ? await storage.lowlevel.httpGet(textOf(result.download_url)) : Buffer.from(textOf(result.content_base64 ?? result.content), 'base64');
+                    return { content_base64: Buffer.from(data).toString('base64'), size_bytes: data.byteLength };
+                }
+                for (const key of ['offset', 'limit'])
+                    if (params[key] != null)
+                        options[key] = Number(params[key]);
+                const data = await storage.readBytes(remotePath, options);
+                return { content_base64: Buffer.from(data).toString('base64'), size_bytes: data.byteLength };
+            }
+            const fields = { list: ['page', 'size', 'marker', 'long', 'recursive'], find: ['name', 'mtime', 'page'], du: [] };
+            for (const key of fields[operation] ?? [])
+                if (params[key] != null)
+                    options[key] = params[key];
+            if (params.page_size != null || params.pageSize != null)
+                options.pageSize = Number(params.page_size ?? params.pageSize);
+            if (params.max_depth != null || params.maxDepth != null)
+                options.maxDepth = Number(params.max_depth ?? params.maxDepth);
+            if (params.node_type != null || params.nodeType != null)
+                options.nodeType = params.node_type ?? params.nodeType;
+            if (operation === 'find' && (params.size_expr != null || params.sizeExpr != null))
+                options.size = params.size_expr ?? params.sizeExpr;
+            const method = storage[operation === 'ls' ? 'list' : operation];
+            return await method.call(storage, ...(operation === 'df' ? [options] : [remotePath, options]));
+        };
+        try {
+            const count = Math.max(1, Number(params.count || 1));
+            const values = await cacheReadContext.run(counters, async () => {
+                if (params.concurrent)
+                    return await Promise.all(Array.from({ length: count }, () => readOnce()));
+                const items = [];
+                for (let index = 0; index < count; index += 1)
+                    items.push(await readOnce());
+                return items;
+            });
+            if (values.some((value) => stableStringify(value) !== stableStringify(values[0])))
+                throw new Error('cache_read returned inconsistent values');
+            const result = operation === 'read_bytes' ? jsonObjectOf(values[0]) : { value: values[0] };
+            return { ...result, ...counters };
+        }
+        finally {
+            releaseCall();
+            releaseHttp();
+        }
+    }
     async callStorageAction(action, params) {
+        if (action === 'cache_read')
+            return await this.cacheRead(params);
         const storage = this.client.storage;
         const path = textOf(params.path).trim();
         const owner = textOf(params.owner_aid ?? params.ownerAID).trim() || undefined;
@@ -1896,7 +2604,10 @@ export class CrossSdkTsAgent {
             case 'revoke_share_link':
                 return await storage.lowlevel.revokeShareLink({ shareId: textOf(params.share_id ?? params.shareId).trim() });
             case 'get_by_share': {
-                const result = await storage.lowlevel.getByShare({ shareId: textOf(params.share_id ?? params.shareId).trim() });
+                const result = await storage.lowlevel.getByShare({
+                    shareId: textOf(params.share_id ?? params.shareId).trim(),
+                    noCache: Boolean(params.no_cache ?? params.noCache),
+                });
                 const resultObj = jsonObjectOf(result);
                 const content = textOf(resultObj?.content);
                 if (content) {
@@ -2053,6 +2764,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 = {
@@ -2186,7 +2898,7 @@ export class CrossSdkTsAgent {
     aidStore() {
         return new AIDStore({
             aunPath: this.aunPath,
-            encryptionSeed: '',
+            encryptionSeed: process.env.AUN_TEST_ENCRYPTION_SEED || process.env.AUN_ENCRYPTION_SEED || '',
             slotId: this.slotId,
             debug: this.debug,
         });