@agentunion/fastaun 0.5.33 → 0.5.35

package/dist/client.js

@@ -26,6 +26,8 @@ import { AUNLogger } from './logger.js';
 import { normalizeGroupId } from './group-id.js';
 import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { RPCTransport } from './transport.js';
+import { UdpStandbyController } from './udp-standby.js';
+import { SyncChannels } from './client/sync-channels.js';
 import { AuthFlow } from './auth.js';
 import { AgentMdManager, buildDefaultAgentMd, updateOwnershipAgentMd } from './agent-md.js';
 import { AgentMdChangeCoordinator } from './agent-md-changes.js';
@@ -908,6 +910,9 @@ export class AUNClient {
     _discovery;
     /** 传输层 */
     _transport;
+    _udpStandby = null;
+    _udpStandbyPolicy;
+    _udpStandbyConnectOptions;
     /** 认证流程 */
     _auth;
     resolveCredentialService;
@@ -931,6 +936,8 @@ export class AUNClient {
     _groupIdentityOperations = new Map();
     _entityOwnershipConnection = 0;
     _entityOwnershipChecks = new Map();
+    _postConnectRecoveryTimer = null;
+    _postConnectRecoveryAbort = null;
     _groupIndexMetaCache = new GroupIndexMetaCache();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _p2pPeerPullEnabled = true;
@@ -1050,6 +1057,7 @@ export class AUNClient {
     _peerDirectory;
     _lifecycle;
     _rpcPipeline;
+    _syncChannelCoordinator = null;
     _delivery;
     _v2E2EE;
     _groupState;
@@ -1161,6 +1169,7 @@ export class AUNClient {
         this._installRiskHooks();
         this._transport.setClassMessageHandler((event, payload) => this._controlMessages().onPush(payload, event.includes('group.')));
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
+        this._transport.setSyncControlObserver((meta, method, params) => this._historyChannels().observe(meta, method, params));
         this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
         this._transport._onForegroundDrained = () => this._delivery.onForegroundPullsDrained();
@@ -1351,6 +1360,11 @@ export class AUNClient {
         const client = new AUNClient(AID._create({ aid: aid.aid, aunPath: aid.aunPath, certPem: aid.certPem, privateKeyPem: aid.privateKeyPem,
             certValid: aid.isCertValid(), privateKeyValid: aid.isPrivateKeyValid(), deviceId: this._deviceId, slotId,
             verifySsl: aid.verifySsl, rootCaPath: aid.rootCaPath, debug: aid.debug, aidStore: aid._aidStore }));
+        const identity = this._auth.loadIdentityOrNone(), token = String(identity?.access_token ?? ''), expiresAt = identity?.access_token_expires_at;
+        if (identity?.aid === aid.aid && token.startsWith('eyJ') && token.split('.').length === 3
+            && typeof expiresAt === 'number' && expiresAt > Date.now() / 1000 + 30) {
+            Object.assign(client._identity, { access_token: token, access_token_expires_at: expiresAt });
+        }
         client._ownershipOperation = true;
         client._ownershipType = this.getType();
         return client;
@@ -1590,6 +1604,10 @@ export class AUNClient {
     }
     _applyAidRuntimeContext(aid) {
         this._aidStore = aid._aidStore;
+        this._udpStandby?.close();
+        this._udpStandby = null;
+        this._udpStandbyPolicy = undefined;
+        this._udpStandbyConnectOptions = undefined;
         const oldTransport = this._transport;
         try {
             const closeResult = oldTransport?.close?.();
@@ -1693,6 +1711,7 @@ export class AUNClient {
         this._installRiskHooks();
         this._transport.setClassMessageHandler((event, payload) => this._controlMessages().onPush(payload, event.includes('group.')));
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
+        this._transport.setSyncControlObserver((meta, method, params) => this._historyChannels().observe(meta, method, params));
         this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
         this._transport._onForegroundDrained = () => this._delivery.onForegroundPullsDrained();
@@ -1748,6 +1767,56 @@ export class AUNClient {
         return this._peerDirectory.peers();
     }
     /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
+    _historyChannels() {
+        return this._syncChannelCoordinator ??= new SyncChannels({
+            main: () => this._transport,
+            current: () => this._state === 'ready' && !this._closing && this._transport.isConnected(),
+            wake: () => this._delivery?.requestBackgroundPullRecovery(),
+            owner: () => String(this._aid ?? ''),
+            namespace: (method, params) => this._rpcPipeline.pullGateKeyForCall(method, params).split('|')[0],
+            pendingNamespaces: () => [...this._delivery.pendingHistoryNamespaces(), ...this._rpcPipeline.pendingHistoryNamespaces()],
+            fail: (method, params, error) => this._dispatcher.enqueue('sync.error', { namespace: params.sender_aid ? this._delivery.peerNamespace(String(params.sender_aid)) : `group:${String(params.group_id ?? params.group_aid ?? '')}`, method, code: 'OVERSIZED_MESSAGE', error: error instanceof Error ? error.message : String(error) }),
+            create: async (parent, timeout = 35000, signal) => {
+                const deadline = Date.now() + timeout;
+                const dispatcher = new EventDispatcher(this._logger.for('aun_core.events'));
+                const transport = new RPCTransport({ eventDispatcher: dispatcher, rpcBudget: this._transport.rpcBudget, syncAuxiliary: true,
+                    timeout, verifySsl: this._configModel.verifySsl, logger: this._logger.for('aun_core.transport') });
+                transport.setSyncControlObserver((meta, method, params) => this._historyChannels().observe(meta, method, params));
+                transport.setRequestAdmission(this._transport._requestAdmission);
+                transport.setRequestCheck(this._transport._requestCheck);
+                transport.setProtocolDisconnectCallback(() => this._historyChannels().auxiliaryDisconnected(transport));
+                const abort = () => { void transport.close(); };
+                signal?.addEventListener('abort', abort, { once: true });
+                try {
+                    if (signal?.aborted)
+                        throw new TimeoutError('history sync cancelled', { retryable: true });
+                    const challenge = await transport.connect(this._gatewayUrl);
+                    if (Date.now() >= deadline || signal?.aborted)
+                        throw new TimeoutError('history sync deadline exceeded', { retryable: true });
+                    transport.setTimeout(Math.max(1, deadline - Date.now()));
+                    const token = AuthFlow._getCachedAccessToken(this._identity ?? {})
+                        || AuthFlow._getCachedAccessToken(this._sessionParams ?? {});
+                    if (!token)
+                        throw new ConnectionError('auxiliary sync connection has no valid access token');
+                    const hello = await this._auth.initializeWithToken(transport, challenge, token, { deviceId: this._deviceId,
+                        slotId: this._slotId, connectionKind: 'short', shortTtlMs: 0, extraInfo: { _sync_parent: parent } });
+                    if (!isJsonObject(hello.connection) || !hello.connection.id)
+                        throw new ConnectionError('auxiliary sync connection has no identity');
+                    if (!isJsonObject(hello.negotiated_capabilities) || hello.negotiated_capabilities.elastic_connections_v1 !== true || hello.negotiated_capabilities.sync_channels_v1 !== true)
+                        throw new ConnectionError('auxiliary sync capabilities were not negotiated');
+                    return { id: String(hello.connection.id), transport, dispose: () => dispatcher.close() };
+                }
+                catch (error) {
+                    await transport.close();
+                    await dispatcher.close();
+                    throw error;
+                }
+                finally {
+                    signal?.removeEventListener('abort', abort);
+                }
+            },
+        });
+    }
     _observeRpcMeta(meta) {
         this._agentMdManager.observeRpcMeta(meta, this._aid);
         this._groupIndexMetaCache.observeRpcMeta(meta, { localAid: this._aid ?? '' });
@@ -1791,10 +1860,14 @@ export class AUNClient {
     }
     /** 连接到 Gateway；身份来自构造函数或 loadIdentity(aid)，认证由 SDK 内部自动完成。 */
     async connect(opts) {
+        if (this._udpStandby && ['standby', 'preparing', 'waking'].includes(this._udpStandby.state))
+            return this._udpStandby.ensureActive();
+        this._udpStandbyConnectOptions = opts ? { ...opts } : undefined;
         await this._lifecycle.connect(opts);
     }
     /** 关闭连接 */
     async close() {
+        this._udpStandby?.close();
         this._risk.close();
         this._peerGatewayCache.clear();
         return this._lifecycle.close();
@@ -1804,6 +1877,7 @@ export class AUNClient {
      * disconnect 是可恢复的：停止心跳、关闭 WebSocket，但不清理 keystore 等状态。
      */
     async disconnect() {
+        this._udpStandby?.close();
         return this._lifecycle.disconnect();
     }
     get riskState() { return Object.freeze(structuredClone(this._risk.state)); }
@@ -1961,27 +2035,47 @@ export class AUNClient {
      * 自动处理内部方法限制、E2EE 加解密、客户端签名等。
      */
     async call(method, params, options) {
-        const assertCurrent = ['group.transfer_owner', 'org.lifecycle.transfer', 'group.dissolve', 'org.lifecycle.dissolve'].includes(method) ? this._entityOwnershipGuard() : undefined;
-        const recoverOwnership = ['group.transfer_owner', 'org.lifecycle.transfer', 'group.dissolve', 'org.lifecycle.dissolve'].includes(method) ? await this._prepareEntityOwnershipLifecycle(method, params ?? {}) : undefined;
-        await this._checkEntityOwnershipOnAccess(method, params ?? {});
-        const readIdentity = ['message.read', 'message.read_state', 'group.read', 'group.read_state'].includes(method)
-            ? this._ensureReadStateIdentity() : null;
-        try {
-            const result = await (options === undefined ? this._rpcPipeline.call(method, params, assertCurrent) : this._rpcPipeline.call(method, params, assertCurrent, options));
-            await this._safeAsync(this._getCredentialRenewal().observe(method, params ?? {}, result));
-            if (readIdentity !== null && readIdentity === this._ensureReadStateIdentity())
-                this._observeReadStateResult(method, result, params ?? {});
-            return result;
+        const echoStarted = performance.now();
+        if ((method === 'message.send' || method === 'group.send') && params && this._isEchoPayload(params.payload ?? params.content)) {
+            params = { ...params };
+            this._echoStarts.set(params, echoStarted);
+        }
+        const lifecycle = ['group.transfer_owner', 'org.lifecycle.transfer', 'group.dissolve', 'org.lifecycle.dissolve'].includes(method);
+        let standbyRelease;
+        if (lifecycle && this._udpStandby) {
+            const deadline = Math.min(options?.deadline ?? Infinity, typeof params?._rpc_deadline === 'number' ? params._rpc_deadline : Infinity, Date.now() + Number(this._sessionOptions?.timeouts?.call ?? 35) * 1000);
+            standbyRelease = await this._udpStandby.acquire(method, deadline);
+            options = { ...options, deadline };
         }
-        catch (err) {
-            if (recoverOwnership) {
-                try {
-                    await recoverOwnership(err);
+        try {
+            const assertCurrent = lifecycle ? this._entityOwnershipGuard() : undefined;
+            const recoverOwnership = lifecycle ? await this._prepareEntityOwnershipLifecycle(method, params ?? {}) : undefined;
+            await this._checkEntityOwnershipOnAccess(method, params ?? {});
+            const readIdentity = ['message.read', 'message.read_state', 'group.read', 'group.read_state'].includes(method)
+                ? this._ensureReadStateIdentity() : null;
+            try {
+                const result = await (options === undefined ? this._rpcPipeline.call(method, params, assertCurrent) : this._rpcPipeline.call(method, params, assertCurrent, options));
+                await this._safeAsync(this._getCredentialRenewal().observe(method, params ?? {}, result));
+                if (readIdentity !== null && readIdentity === this._ensureReadStateIdentity())
+                    this._observeReadStateResult(method, result, params ?? {});
+                return result;
+            }
+            catch (err) {
+                if (recoverOwnership) {
+                    try {
+                        await recoverOwnership(err);
+                    }
+                    catch { }
                 }
-                catch { }
+                await this._maybeHandleHalfOpenRpcFailure(err);
+                const returned = await this._echoFailure(method, params, err);
+                if (returned)
+                    return returned;
+                throw err;
             }
-            await this._maybeHandleHalfOpenRpcFailure(err);
-            throw err;
+        }
+        finally {
+            standbyRelease?.();
         }
     }
     _entityOwnershipGuard() {
@@ -2081,7 +2175,7 @@ export class AUNClient {
                         return await existing;
                     this._entityOwnershipChecks.set(`${identity}:${aid}`, task);
                 }
-                const consensus = await this.checkOwnershipConsensus(aid);
+                const consensus = await this.checkOwnershipConsensus(aid, true);
                 if (consensus.status === 'consensus' && consensus.owner_aid === this._aid)
                     return true;
                 await this._completeEntityOwnership(aid, type, undefined, () => {
@@ -2209,9 +2303,27 @@ export class AUNClient {
                 const groupId = String(params.group_aid ?? params.groupAid ?? params.group_id ?? params.groupId ?? message.slice(prefix.length)).trim();
                 const target = normalizeGroupId(groupId.toLowerCase(), { localIssuer: this._aid?.split('.').slice(1).join('.') });
                 const key = `${this._aid}:${this._serviceEventIdentityVersion}:${this._entityOwnershipConnection}:${target}`;
-                if (!this._entityOwnershipChecks.has(key))
-                    await this._checkEntityOwnershipOnAccess('group.get_info', { group_id: groupId });
-                return await this._entityOwnershipChecks.get(key) ?? false;
+                const assertCurrent = this._entityOwnershipGuard();
+                try {
+                    assertCurrent();
+                    const pending = this._groupIdentityOperations.get(key);
+                    if (pending && !['group.create', 'group.bind_group_aid'].includes(_method)) {
+                        const local = this._aidStore?.load(target);
+                        if (!local?.ok || !local.data.aid.isPrivateKeyValid()) {
+                            await pending.task;
+                            assertCurrent();
+                            return true;
+                        }
+                    }
+                    if (!this._entityOwnershipChecks.has(key))
+                        await this._checkEntityOwnershipOnAccess('group.get_info', { group_id: groupId });
+                    const recovered = await this._entityOwnershipChecks.get(key) ?? false;
+                    assertCurrent();
+                    return recovered;
+                }
+                catch {
+                    return false;
+                }
             }
         }
         const agentPrefix = 'valid agent.md is required for ';
@@ -2260,17 +2372,14 @@ export class AUNClient {
         catch (exc) {
             this._clientLog.warn(`post-connect agent.md check failed: ${formatCaughtError(exc)}`);
         }
-        const store = this._aidStore;
-        if (!store)
-            return;
-        await this._resumeOrgIdentityAfterConnect(store);
     }
     async _runGroupIdentityOperation(groupId, operation, context = '') {
         const aid = String(this._aid ?? '').trim();
         const dot = aid.indexOf('.');
-        const key = normalizeGroupId(groupId, { localIssuer: dot >= 0 ? aid.slice(dot + 1) : '' }).toLowerCase();
-        if (!key)
+        const target = normalizeGroupId(groupId, { localIssuer: dot >= 0 ? aid.slice(dot + 1) : '' }).toLowerCase();
+        if (!target)
             return operation();
+        const key = `${this._aid}:${this._serviceEventIdentityVersion}:${this._entityOwnershipConnection}:${target}`;
         const pending = this._groupIdentityOperations.get(key);
         if (pending && pending.context !== context)
             throw ownershipFailure('conflict', 'pending Org creation context changed');
@@ -2354,12 +2463,42 @@ export class AUNClient {
         tokens.saveMetadata(orgAid, { org_identity_creation: null });
         return checkpoint.result;
     }
-    async _resumeOrgIdentityAfterConnect(store) {
+    _schedulePostConnectRecovery() {
+        this._postConnectRecoveryAbort?.abort();
+        if (this._postConnectRecoveryTimer !== null)
+            clearTimeout(this._postConnectRecoveryTimer);
+        this._postConnectRecoveryTimer = null;
+        const store = this._aidStore;
+        if (this._sessionOptions.background_sync === false)
+            return;
+        const abort = new AbortController();
+        this._postConnectRecoveryAbort = abort;
+        const aid = this._aid, version = this._serviceEventIdentityVersion, connection = this._entityOwnershipConnection;
+        const current = () => !abort.signal.aborted && aid === this._aid && version === this._serviceEventIdentityVersion && connection === this._entityOwnershipConnection && ['ready', 'connected'].includes(this._state) && !this._closing && !this._disconnecting;
+        this._postConnectRecoveryTimer = setTimeout(() => {
+            this._postConnectRecoveryTimer = null;
+            if (!current())
+                return;
+            this._safeAsync(this._delivery.restoreMessageClassPulls());
+            void this._fillP2pGap().catch((exc) => {
+                this._clientLog.warn(`schedule post-connect P2P gap fill failed: ${formatCaughtError(exc)}`);
+            });
+            if (store && !this._ownershipOperation)
+                this._safeAsync(this._resumeOrgIdentityAfterConnect(store, current));
+        }, 30_000 + Math.random() * 30_000);
+        this._postConnectRecoveryTimer.unref?.();
+    }
+    async _resumeOrgIdentityAfterConnect(store, current = () => true) {
+        if (!current())
+            return;
         const keyStore = store._keystore;
         const tokens = store._tokenStore;
         if (typeof keyStore?.listIdentities !== 'function' || typeof tokens?.loadMetadata !== 'function')
             return;
         for (const aid of keyStore.listIdentities()) {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            if (!current())
+                return;
             const metadata = typeof tokens._loadMetadataStrict === 'function' ? tokens._loadMetadataStrict(aid) : tokens.loadMetadata(aid);
             const creation = metadata?.org_identity_creation;
             const transfer = metadata?.org_identity_transfer;
@@ -3534,6 +3673,8 @@ export class AUNClient {
     // ── 事件自动解密管线 ──────────────────────────────────────
     /** 处理 transport 层推送的原始 P2P 消息 */
     async _onRawMessageReceived(data) {
+        if (isJsonObject(data))
+            this._echoStarts.set(data, performance.now());
         if (this._controlMessages().onPush(data))
             return;
         return this._delivery.onRawMessageReceived(data);
@@ -3543,6 +3684,8 @@ export class AUNClient {
     }
     /** 处理群组消息推送：自动解密后 re-publish */
     async _onRawGroupMessageCreated(data) {
+        if (isJsonObject(data))
+            this._echoStarts.set(data, performance.now());
         if (this._controlMessages().onPush(data, true))
             return;
         return this._delivery.onRawGroupMessageCreated(data);
@@ -3657,21 +3800,70 @@ export class AUNClient {
         const ms = String(now.getMilliseconds()).padStart(3, '0');
         return `${hh}:${mm}:${ss}.${ms}`;
     }
+    _echoStarts = new WeakMap();
     _isEchoPayload(payload) {
         if (!payload || typeof payload !== 'object' || Array.isArray(payload))
             return false;
         const text = payload.text;
-        if (typeof text !== 'string' || text.length > 4096)
+        if (typeof text !== 'string')
             return false;
-        return text.split('\n', 1)[0].toLowerCase().includes('echo');
+        const first = text.split('\n', 1)[0].trimStart();
+        return /^(?:echo\.(?:ecdiag|ask)(?:\s|$)|echo(?:\s|\[|$))/i.test(first);
+    }
+    _echoHop(payload) {
+        if (Number.isInteger(payload.hop)) {
+            if (!Number.isSafeInteger(payload.hop))
+                throw new ValidationError('echo hop must be a JSON safe integer');
+            return Number(payload.hop);
+        }
+        const limit = /(?:^|\s)hop=([+-]?\d+)(?=\s|$)/i.exec(payload.text.split('\n', 1)[0]);
+        const hop = limit ? Number(limit[1]) : 100;
+        if (!Number.isSafeInteger(hop))
+            throw new ValidationError('echo hop must be a JSON safe integer');
+        return hop;
+    }
+    _isEchoReturn(payload) {
+        return this._echoHop(payload) < 0 || payload.dir === 'ret' || payload.dir !== 'fwd' && payload.text.split('\n').some(line => line.trim() === '[AUN-Echo.return]');
+    }
+    _appendEchoTrace(payload, stage, started, endpoint = false) {
+        const previousHop = this._echoHop(payload);
+        const returning = endpoint || this._isEchoReturn(payload);
+        const hop = returning ? previousHop - 1 : Math.max(previousHop - 1, 0);
+        if (!Number.isSafeInteger(hop))
+            throw new ValidationError('echo hop decrement exceeds the JSON safe integer range');
+        const now = new Date();
+        const offset = -now.getTimezoneOffset();
+        const tz = `${offset < 0 ? '-' : '+'}${String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0')}:${String(Math.abs(offset) % 60).padStart(2, '0')}`;
+        const uptime = this._connectedAt ? Math.floor((now.getTime() - this._connectedAt) / 1000) : 0;
+        const duration = Math.max(0, Math.round((performance.now() - started) * 1000) / 1000);
+        const trace = `${this._echoTimestamp()} [AUN-SDK.${stage}] dir=${returning ? 'ret' : 'fwd'} hop=${hop} enc=0 ver=${VERSION} epoch=${now.getTime()} tz=${tz}${returning ? ` duration_ms=${duration}` : ''} aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
+        const result = { ...payload, type: 'text', hop, dir: returning ? 'ret' : 'fwd', text: payload.text.trimStart() + '\n' + trace };
+        delete result.max_hop;
+        delete result.rhop;
+        return result;
     }
     _maybeAppendEchoTraceSend(params) {
+        const reflected = params._echo_reflection === true;
+        delete params._echo_reflection;
+        for (const key of ['hop', 'max_hop', 'rhop', 'dir'])
+            delete params[key];
         const payload = params.payload;
-        if (!this._isEchoPayload(payload))
-            return;
-        const uptime = this._connectedAt ? Math.floor((Date.now() - this._connectedAt) / 1000) : 0;
-        const trace = `${this._echoTimestamp()} [AUN-SDK.send] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
-        params.payload = { ...payload, text: payload.text + '\n' + trace };
+        if (!this._isEchoPayload(payload)) {
+            if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+                const clean = { ...payload };
+                for (const key of ['hop', 'max_hop', 'rhop', 'dir'])
+                    delete clean[key];
+                params.payload = clean;
+            }
+            return false;
+        }
+        if (reflected)
+            return false;
+        const started = this._echoStarts.get(params) ?? performance.now();
+        this._echoStarts.set(params, started);
+        const next = this._appendEchoTrace(payload, 'send', started);
+        params.payload = next;
+        return next.dir === 'fwd' && next.hop === 0;
     }
     _shouldSkipEventSignature(event) {
         if (event.encrypted || event.encrypt)
@@ -3679,14 +3871,79 @@ export class AUNClient {
         return this._isEchoPayload(event.payload);
     }
     _maybeAppendEchoTraceReceive(msg) {
-        if (msg.encrypted)
-            return;
+        if (msg.encrypted || msg.encrypt)
+            return false;
         const payload = msg.payload;
-        if (!this._isEchoPayload(payload))
+        if (!this._isEchoPayload(payload) || String(payload.type ?? '').startsWith('e2ee.') || payload.ciphertext)
+            return false;
+        const started = this._echoStarts.get(msg) ?? performance.now();
+        this._echoStarts.set(msg, started);
+        const next = this._appendEchoTrace(payload, 'receive', started);
+        msg.payload = next;
+        return next.dir === 'fwd' && next.hop === 0;
+    }
+    async _returnReceivedEcho(msg) {
+        const payload = msg.payload;
+        const sender = String(msg.from ?? msg.sender_aid ?? msg.from_aid ?? '');
+        const returned = this._appendEchoTrace(payload, 'receive', this._echoStarts.get(msg) ?? performance.now(), true);
+        returned.text = String(returned.text) + '\n[AUN-Echo.return]';
+        const groupId = String(msg.group_id ?? '');
+        await this._rpcPipeline.call('message.send', {
+            to: sender, encrypt: false, _echo_reflection: true,
+            ...(groupId ? { group_id: groupId } : {}),
+            payload: returned,
+        });
+    }
+    async _echoFailure(method, params, error, traced = false) {
+        if (!['message.send', 'group.send'].includes(method) || !params || !this._isEchoPayload(params.payload) || !(error instanceof AUNError) || error instanceof AuthError || error._echoDeliveryAttempted)
+            return;
+        const payload = params.payload;
+        if (String(payload.type ?? '').toLowerCase().startsWith('e2ee') || payload.ciphertext)
             return;
-        const uptime = this._connectedAt ? Math.floor((Date.now() - this._connectedAt) / 1000) : 0;
-        const trace = `${this._echoTimestamp()} [AUN-SDK.receive] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
-        msg.payload = { ...payload, text: payload.text + '\n' + trace };
+        const started = this._echoStarts.get(params) ?? performance.now();
+        let sent;
+        try {
+            sent = traced ? payload : this._appendEchoTrace(payload, 'send', started);
+        }
+        catch {
+            return;
+        }
+        const reason = error instanceof TimeoutError || error.code === -32011 ? 'timeout' : 'send_failed';
+        const state = error instanceof ValidationError || error instanceof ConnectionError && /not connected|closing|closed/i.test(error.message) ? 'not_delivered' : 'unknown';
+        const detail = { code: error.code, message: error.message, data: error.data };
+        const result = { status: 'echo_return', message_id: params.message_id ?? `m-${crypto.randomUUID()}`, from: params.to ?? params.group_id, to: this._aid, payload: sent, reason, delivery_state: state, echo_error: detail };
+        if (method === 'group.send')
+            result.group_id = params.group_id;
+        await this._publishEchoReturn(method, params, result);
+        return result;
+    }
+    async _publishEchoReturn(method, params, result) {
+        if (!this._isEchoPayload(result.payload))
+            return;
+        const payload = result.payload;
+        const returnedPayload = this._appendEchoTrace(payload, 'receive', this._echoStarts.get(params) ?? performance.now(), !this._isEchoReturn(payload));
+        if (result.echo_error)
+            returnedPayload.text += ` reason=${result.reason} delivery_state=${result.delivery_state} error=${JSON.stringify(result.echo_error)}`;
+        if (!String(returnedPayload.text).split('\n').some(line => line.trim() === '[AUN-Echo.return]'))
+            returnedPayload.text += '\n[AUN-Echo.return]';
+        result.payload = returnedPayload;
+        if (this._state === 'closed')
+            return;
+        const groupId = String(result.group_id ?? params.group_id ?? params.group_aid ?? '');
+        const sender = String(result.from ?? result.sender_aid ?? params.to ?? this._aid ?? '');
+        try {
+            await this._publishAppEvent(method === 'group.send' ? 'group.message_created' : 'message.received', {
+                ...result,
+                message_id: String(result.message_id ?? params.message_id ?? ''),
+                from: sender, sender_aid: sender, to: this._aid ?? '', encrypted: false,
+                ...(groupId ? { group_id: groupId } : {}), payload: returnedPayload,
+            }, 'echo_return');
+        }
+        catch (error) {
+            if (error instanceof Error)
+                error._echoDeliveryAttempted = true;
+            throw error;
+        }
     }
     _debugJson(value) {
         const seen = new WeakSet();
@@ -4560,6 +4817,7 @@ export class AUNClient {
     // ── 内部：连接 ────────────────────────────────────────────
     /** 执行一次连接流程 */
     async _connectOnce(params, allowReauth, reconnectOwner, connectionOwner) {
+        this._syncChannelCoordinator?.reset();
         await this._restoreRiskState();
         this._assertRiskReconnect();
         this._riskNegotiated = false;
@@ -4577,6 +4835,10 @@ export class AUNClient {
             : {};
         const capabilities = isJsonObject(extraInfo._capabilities) ? { ...extraInfo._capabilities } : {};
         delete capabilities.message_classes_v1;
+        if (params.udp_standby !== false && params.connection_kind !== 'short')
+            capabilities.udp_standby_v1 = true;
+        else
+            delete capabilities.udp_standby_v1;
         if (typeof this._tokenStore.updateInstanceState === 'function') {
             capabilities.message_classes_v2 = { p2p: ['normal', 'control', 'sdk_control'], group: ['normal', 'control'] };
             capabilities.sdk_control_protocols = { 'aun.agent_md.changed': [1], 'aun.pubsub': [1] };
@@ -4599,12 +4861,21 @@ export class AUNClient {
             const challenge = await this._transport.connect(gatewayUrl);
             this._assertReconnectOwner(reconnectOwner);
             this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
-            const authTransport = reconnectOwner ? {
+            const authTransport = {
                 call: (...args) => {
                     this._assertReconnectOwner(reconnectOwner);
+                    this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
                     return this._transport.call(...args);
                 },
-            } : this._transport;
+                connect: async (url) => {
+                    this._assertReconnectOwner(reconnectOwner);
+                    this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
+                    const nextChallenge = await this._transport.connect(url);
+                    this._assertReconnectOwner(reconnectOwner);
+                    this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
+                    return nextChallenge;
+                },
+            };
             this._clientLog.debug(`WebSocket connection established: gateway=${gatewayUrl}`);
             this._state = 'authenticating';
             if (allowReauth) {
@@ -4637,6 +4908,7 @@ export class AUNClient {
                     this._bindGatewayRuntimeIdentity(auth.hello, params);
                     this._gatewayConnectionId = isJsonObject(auth.hello) && isJsonObject(auth.hello.connection) ? String(auth.hello.connection.id ?? '') : '';
                     this._negotiatedCapabilities = isJsonObject(auth.hello) && isJsonObject(auth.hello.negotiated_capabilities) ? auth.hello.negotiated_capabilities : {};
+                    this._udpStandbyPolicy = isJsonObject(auth.hello) && isJsonObject(auth.hello.udp_standby) ? auth.hello.udp_standby : undefined;
                     if (isJsonObject(auth.hello))
                         await this._applyRiskHello(auth.hello);
                 }
@@ -4659,6 +4931,7 @@ export class AUNClient {
                 this._bindGatewayRuntimeIdentity(hello, params);
                 this._gatewayConnectionId = isJsonObject(hello) && isJsonObject(hello.connection) ? String(hello.connection.id ?? '') : '';
                 this._negotiatedCapabilities = isJsonObject(hello) && isJsonObject(hello.negotiated_capabilities) ? hello.negotiated_capabilities : {};
+                this._udpStandbyPolicy = isJsonObject(hello) && isJsonObject(hello.udp_standby) ? hello.udp_standby : undefined;
                 if (isJsonObject(hello))
                     await this._applyRiskHello(hello);
             }
@@ -4671,6 +4944,7 @@ export class AUNClient {
             this._migrationPending = false;
             this._lastDisconnectInfo = null;
             this._state = 'ready';
+            this._historyChannels().bind(this._gatewayConnectionId, this._negotiatedCapabilities.elastic_connections_v1 === true && this._negotiatedCapabilities.sync_channels_v1 === true && params.connection_kind !== 'short');
             this._connectedAt = Date.now();
             if (Array.isArray(params.gateways)) {
                 this._gatewayCandidates = [...new Set(params.gateways
@@ -4728,19 +5002,16 @@ export class AUNClient {
             this._agentMdChanges = new AgentMdChangeCoordinator(this);
             // connect/reconnect 成功后自动触发一次 P2P message.v2.pull，补齐离线期间积压
             // 群消息按惰性触发，不在此处主动 pull
-            if (backgroundSyncEnabled) {
-                void this._fillP2pGap().catch((exc) => {
-                    this._clientLog.warn(`schedule post-connect P2P gap fill failed: ${formatCaughtError(exc)}`);
-                });
-            }
             this._entityOwnershipConnection++;
             this._entityOwnershipChecks.clear();
             if (!this._ownershipOperation)
                 this._safeAsync(this._checkIdentityAdmissionAfterConnect());
-            this._safeAsync(this._delivery.restoreMessageClassPulls());
+            if (backgroundSyncEnabled)
+                this._schedulePostConnectRecovery();
             if (!isShortConnection && backgroundSyncEnabled && this._v2Session) {
                 this._safeAsync(this._v2AutoConfirmPendingProposals());
             }
+            this._activateUdpStandby();
             this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl}, aid=${this._aid ?? ''}`);
         }
         catch (err) {
@@ -5663,6 +5934,12 @@ export class AUNClient {
     }
     /** 停止所有后台任务 */
     _stopBackgroundTasks() {
+        this._postConnectRecoveryAbort?.abort();
+        this._postConnectRecoveryAbort = null;
+        if (this._postConnectRecoveryTimer !== null)
+            clearTimeout(this._postConnectRecoveryTimer);
+        this._postConnectRecoveryTimer = null;
+        this._syncChannelCoordinator?.reset();
         this._stopCredentialRenewal();
         this._auth.invalidateStrictPkiCache();
         this._certCache.clear();
@@ -6056,6 +6333,8 @@ export class AUNClient {
     }
     /** 传输层断线回调 */
     async _handleTransportDisconnect(error, closeCode, initialOptions) {
+        if (this._udpStandby?.handlesDisconnect())
+            return;
         if (this._closing || this._disconnecting || this.state === ConnectionState.CLOSED)
             return;
         // 已在重连中则跳过，避免心跳超时和 transport 断线回调重复触发
@@ -6136,6 +6415,50 @@ export class AUNClient {
         }
         this._startReconnect(serverInitiated, initialOptions, reconnectAbort);
     }
+    _activateUdpStandby() {
+        if (this._negotiatedCapabilities.udp_standby_v1 !== true || this._udpStandbyPolicy?.enabled !== true) {
+            this._udpStandby?.deactivate();
+            this._transport.setStandbyGate(null);
+            return;
+        }
+        this._udpStandby ??= new UdpStandbyController({
+            call: (method, params, timeout) => this._transport.call(method, params, timeout),
+            canPrepare: async (timeout) => {
+                if (!this._aid)
+                    return true;
+                try {
+                    if (!this._aidStore) {
+                        const record = this._agentMdManager?._loadRecord?.(this._aid, true) ?? this._agentMdManager?.loadRecord(this._aid);
+                        const content = String(record?.local_draft_content ?? '') || String(record?.content ?? '');
+                        return !content || validateAgentMdReadDocument(content).frontmatter.type !== 'human';
+                    }
+                    const result = await this._aidStore.resolve(this._aid, { timeout });
+                    return !result.ok || result.data?.agent_md?.frontmatter.type !== 'human';
+                }
+                catch {
+                    return true;
+                }
+            },
+            canStandby: () => this._state === 'ready' && !this._closing && !this._disconnecting && !this._reconnectActive
+                && this._sessionOptions?.background_sync !== false
+                && this._groupIdentityOperations.size === 0
+                && this._transport.isConnected() && this._transport.rpcBudget.counts.total === 0
+                && this._transport.foregroundWaiting === 0 && this._transport.rpcBudget.backgroundWaiting === 0
+                && this._dispatcher.isIdle && !this._delivery?.hasAnyPendingPull()
+                && (this._syncChannelCoordinator?.isIdle ?? true),
+            prepareParams: () => ({ connection_id: this._gatewayConnectionId }),
+            detach: () => this._transport.close(),
+            reconnect: async () => {
+                if (this._closing || this._disconnecting)
+                    throw new ConnectionError('client closed');
+                this._state = 'standby';
+                await this._lifecycle.connect(this._udpStandbyConnectOptions);
+            },
+        });
+        this._udpStandby.activate(this._udpStandbyPolicy);
+        const standby = this._udpStandby;
+        this._transport.setStandbyGate((method, deadline, signal) => standby.acquire(method, deadline, signal), () => standby.touch(), params => standby.authenticationParams(params));
+    }
     /** 启动重连循环（默认无限重试 + 当前基数抖动，仅在不可重试错误、close() 或 max_attempts 耗尽时终止） */
     _startReconnect(serverInitiated = false, initialOptions, existingAbort) {
         if (existingAbort) {