@agentunion/fastaun 0.5.34 → 0.5.36

package/dist/client.js

@@ -26,6 +26,7 @@ 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';
@@ -909,6 +910,9 @@ export class AUNClient {
     _discovery;
     /** 传输层 */
     _transport;
+    _udpStandby = null;
+    _udpStandbyPolicy;
+    _udpStandbyConnectOptions;
     /** 认证流程 */
     _auth;
     resolveCredentialService;
@@ -932,6 +936,8 @@ export class AUNClient {
     _groupIdentityOperations = new Map();
     _entityOwnershipConnection = 0;
     _entityOwnershipChecks = new Map();
+    _postConnectRecoveryTimer = null;
+    _postConnectRecoveryAbort = null;
     _groupIndexMetaCache = new GroupIndexMetaCache();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _p2pPeerPullEnabled = true;
@@ -1409,25 +1415,30 @@ export class AUNClient {
         const observation = { root: manager.root, etag: observedEtag, version: Number(record?.observation_version ?? 0), content_hash: typeof record?.content === 'string' ? ownershipSha256(record.content) : '' };
         const cache = this._ownershipConsensusCache ??= new Map();
         const cached = cache.get(target);
-        if (!force && cached?.result.status === 'consensus' && record?.remote_status !== 'missing'
+        if (cached?.result.status === 'consensus' && cached.observedVersion === observation.version && record?.remote_status !== 'missing'
+            && (!record?.remote_owner_md_sha256 || record.remote_owner_md_sha256 === cached.result.owner_md_sha256)
             && (observedEtag === cached.observedEtag || observedEtag === cached.result.agent_md_etag)
             && (typeof record?.content !== 'string' || ownershipSha256(record.content) === cached.result.agent_md_sha256)) {
             cached.observedEtag = observedEtag;
             return { ...cached.result };
         }
-        if (!force && !cached) {
+        if (!cached) {
             const local = manager.localOwnershipConsensus(target, record);
             if (local) {
-                cache.set(target, { observedEtag, result: local });
+                cache.set(target, { observedEtag, observedVersion: observation.version, result: local });
                 return { ...local };
             }
         }
         cache.delete(target);
         const result = { status: 'unavailable', sub_aid: target, owner_aid: null, relation_version: 0, lock: 'unlocked', agent_md_etag: '', agent_md_sha256: '' };
-        const entry = { observedEtag, result: { ...result } };
+        const entry = { observedEtag, observedVersion: observation.version, result: { ...result } };
         cache.set(target, entry);
+        let consensusContent;
         try {
             const snapshot = await manager.readOwnershipFresh(target);
+            consensusContent = snapshot.content;
+            if (snapshot.owner_md_sha256)
+                result.owner_md_sha256 = snapshot.owner_md_sha256;
             Object.assign(result, { relation_version: snapshot.relation_version, lock: snapshot.lock, agent_md_etag: snapshot.etag,
                 agent_md_sha256: snapshot.exists ? ownershipSha256(snapshot.content) : '' });
             if (snapshot.ownership_status)
@@ -1448,11 +1459,15 @@ export class AUNClient {
             result.retryable = result.status === 'unavailable';
         }
         if (this._agentMdManager === manager && this._ownershipConsensusCache === cache && cache.get(target) === entry) {
-            entry.result = { ...result };
             try {
-                manager.cacheOwnershipSnapshot(target, result, observation);
+                if (manager.cacheOwnershipSnapshot(target, result, observation, consensusContent))
+                    entry.result = { ...result };
+                else
+                    cache.delete(target);
+            }
+            catch {
+                cache.delete(target);
             }
-            catch { }
         }
         return result;
     }
@@ -1598,6 +1613,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?.();
@@ -1850,10 +1869,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();
@@ -1863,6 +1886,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)); }
@@ -2020,27 +2044,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() {
@@ -2083,6 +2127,7 @@ export class AUNClient {
             throw ownershipFailure('conflict', 'entity lifecycle ownership action changed');
         const ownership = { statement: declaration.statement, action, ...(transfer ? { transfer: { new_owner_aid: ownershipAid(newOwner, 'new_owner_aid'), target_relation_version: declaration.statement.relation_version + 1, expires_at: Number(params.expires_at ?? Math.floor(Date.now() / 1000) + 3600) } } : {}) };
         const raw = signOwnershipFile(owner, `---\nowner_aid: ${owner.aid}\nsub_aid: ${target}\nownership: ${JSON.stringify(ownership)}\n---\n`, 'owner');
+        await this._getOwnershipFiles().verifyFile(raw, 'owner', target, owner.aid, true);
         await storage.writeOwnerMd(owner.aid, target, raw, original, assertCurrent);
         return async (error) => {
             if (!(error instanceof AUNError) || error instanceof TimeoutError || error instanceof ConnectionError || error.retryable || isJsonObject(error.data) && error.data.committed === true || ![-32602, 4000, 4030, 403].includes(error.code) && !['INVALID_ARGUMENT', 'ROLE_ACCESS_DENIED', 'MEMBER_NOT_FOUND', 'permission_denied', 'member_banned', 'member_blocked'].includes(error.stringCode))
@@ -2228,12 +2273,14 @@ export class AUNClient {
         else {
             const payload = `---\nowner_aid: ${owner.aid}\nsub_aid: ${aid}\nownership: ${JSON.stringify({ statement, action: 'declare' })}\n---\n`;
             const raw = signOwnershipFile(owner, payload, 'owner');
+            await this._getOwnershipFiles().verifyFile(raw, 'owner', aid, owner.aid, true);
             assertCurrent();
             await storage.writeOwnerMd(owner.aid, aid, raw, original, assertCurrent);
         }
         const source = content ?? (observed.exists ? observed.content : buildDefaultAgentMd(aid, { type, name: String(entity.name ?? aid) }));
         const updated = updateOwnershipAgentMd(source, { owner: owner.aid, ownership: { statement } }).replace(/^entity_cert_fingerprint:.*(?:\r?\n|$)/m, '');
         const signed = signOwnershipFile(local.data.aid, updated, 'agent');
+        await this._getOwnershipFiles().verifyFile(signed, 'agent', aid, undefined, true);
         if (content === undefined) {
             if (!previous || previous.owner_aid !== owner.aid || previous.relation_version !== version) {
                 assertCurrent();
@@ -2268,9 +2315,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 ';
@@ -2319,17 +2384,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');
@@ -2413,12 +2475,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;
@@ -3593,6 +3685,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);
@@ -3602,6 +3696,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);
@@ -3716,21 +3812,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)
@@ -3738,14 +3883,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) || 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;
-        if (!this._isEchoPayload(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 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 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 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();
@@ -4637,6 +4847,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] };
@@ -4659,12 +4873,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) {
@@ -4697,6 +4920,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);
                 }
@@ -4719,6 +4943,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);
             }
@@ -4789,19 +5014,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) {
@@ -5724,6 +5946,11 @@ 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();
@@ -6118,6 +6345,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 断线回调重复触发
@@ -6198,6 +6427,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) {