@agentunion/fastaun 0.5.27 → 0.5.28

package/dist/client.d.ts

@@ -12,6 +12,7 @@
  */
 import { AIDStore } from './aid-store.js';
 import { type Subscription, type EventHandler } from './events.js';
+import { type RiskStateEvent } from './risk-control.js';
 import { CollabClient } from './collab/client.js';
 import { DebugFacade, CredentialFacade, OrgFacade, GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
@@ -207,6 +208,13 @@ export declare class AUNClient {
     private _v2KeyStore?;
     private _v2SessionInitInFlight;
     private _v2RuntimeGeneration;
+    private _controlMessageCoordinator?;
+    private _agentMdChanges?;
+    private _agentMdCommitUnsubscribe?;
+    private _installAgentMdChangeHooks;
+    private _getAgentMdChanges;
+    private _onSdkControl;
+    private _controlMessages;
     /** V2 bootstrap 缓存：aid/group:id → 设备列表 + 时间戳 */
     private _v2BootstrapCache;
     private _v2SigCache;
@@ -227,6 +235,15 @@ export declare class AUNClient {
     private _reconnectTask;
     private _reconnectEventDispatchDepth;
     private _gatewayConnectionId;
+    private _negotiatedCapabilities;
+    private _riskNegotiated;
+    private _riskRestoredAid;
+    private _riskEvents;
+    private _riskApplying;
+    private _riskApplyTail;
+    private _riskScalarReconnectAt;
+    private _riskHttpRetryAt;
+    private _risk;
     private _migrationPending;
     private _migrationRevision;
     private _serverKicked;
@@ -366,6 +383,15 @@ export declare class AUNClient {
      * disconnect 是可恢复的：停止心跳、关闭 WebSocket，但不清理 keystore 等状态。
      */
     disconnect(): Promise<void>;
+    get riskState(): Readonly<RiskStateEvent>;
+    private _installRiskHooks;
+    private _restoreRiskState;
+    private _assertRiskReconnect;
+    private _riskReconnectDelay;
+    private _applyRiskHello;
+    private _onRiskControl;
+    private _applyRiskControl;
+    _riskFetch(input: string, init?: RequestInit, perform?: (url: string, init: RequestInit) => Promise<Response>, requestScope?: string): Promise<Response>;
     /**
      * 发送 JSON-RPC 调用。
      * 自动处理内部方法限制、E2EE 加解密、客户端签名等。

package/dist/client.js

@@ -27,6 +27,7 @@ import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { AgentMdManager, buildDefaultAgentMd } from './agent-md.js';
+import { AgentMdChangeCoordinator } from './agent-md-changes.js';
 import { GroupIndexMetaCache } from './group-index.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
@@ -36,6 +37,8 @@ import { IdentityRuntimeManager } from './client/identity.js';
 import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
 import { RpcPipeline } from './client/rpc-pipeline.js';
+import { RiskController } from './risk-control.js';
+import { ControlMessageCoordinator, messageClassOf } from './client/control-messages.js';
 import { CollabClient } from './collab/client.js';
 import { DebugFacade, CredentialFacade, OrgFacade, GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
@@ -929,6 +932,27 @@ export class AUNClient {
     _v2KeyStore;
     _v2SessionInitInFlight = null;
     _v2RuntimeGeneration = 0;
+    _controlMessageCoordinator;
+    _agentMdChanges;
+    _agentMdCommitUnsubscribe;
+    _installAgentMdChangeHooks() {
+        this._agentMdCommitUnsubscribe?.();
+        this._agentMdCommitUnsubscribe = AgentMdManager.subscribeCommits(this._configModel.aunPath, () => {
+            const coordinator = this._getAgentMdChanges();
+            if (this._state === 'ready')
+                void coordinator.flushNotifications().catch((error) => this._clientLog.debug(String(error)));
+            coordinator.schedule();
+        });
+    }
+    _getAgentMdChanges() {
+        return this._agentMdChanges ??= new AgentMdChangeCoordinator(this);
+    }
+    _onSdkControl(protocol, version, payload, senderAid) {
+        return this._getAgentMdChanges().handle(protocol, version, payload, senderAid);
+    }
+    _controlMessages() {
+        return this._controlMessageCoordinator ??= new ControlMessageCoordinator(this);
+    }
     /** V2 bootstrap 缓存：aid/group:id → 设备列表 + 时间戳 */
     _v2BootstrapCache = new Map();
     _v2SigCache = new Map();
@@ -949,6 +973,27 @@ export class AUNClient {
     _reconnectTask = null;
     _reconnectEventDispatchDepth = 0;
     _gatewayConnectionId = '';
+    _negotiatedCapabilities = {};
+    _riskNegotiated = false;
+    _riskRestoredAid = '';
+    _riskEvents = [];
+    _riskApplying = false;
+    _riskApplyTail = Promise.resolve();
+    _riskScalarReconnectAt = 0;
+    _riskHttpRetryAt = new Map();
+    _risk = new RiskController({
+        persist: async (state) => {
+            if (!this._aid || !this._tokenStore.saveMetadata || !isJsonObject(state.target) || state.target.aid !== this._aid || state.target.device_id !== this._deviceId)
+                throw new Error('risk persistence unavailable');
+            this._tokenStore.saveMetadata(this._aid, { ...(this._tokenStore.loadMetadata?.(this._aid) ?? {}), [`risk_state_v1:${this._deviceId}`]: state });
+        },
+        onState: (event) => {
+            if (this._riskApplying)
+                this._riskEvents.push(event);
+            else
+                this._dispatcher.enqueue('risk_state_changed', event);
+        },
+    });
     _migrationPending = false;
     _migrationRevision = new Map();
     _serverKicked = false;
@@ -1059,6 +1104,7 @@ export class AUNClient {
             fetchEntityIdentity: (target, type) => this._freshEntityCertificate(target, type),
             fetchEntitySigner: (target, fingerprint) => this._freshEntitySigner(target, fingerprint),
         });
+        this._installAgentMdChangeHooks();
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: 35_000,
@@ -1066,6 +1112,8 @@ export class AUNClient {
             logger: this._logger.for('aun_core.transport'),
             dnsNet,
         });
+        this._installRiskHooks();
+        this._transport.setClassMessageHandler((event, payload) => this._controlMessages().onPush(payload, event.includes('group.')));
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
         this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
@@ -1100,6 +1148,8 @@ export class AUNClient {
         this._dispatcher.subscribeProtocol('_raw.message.read_changed', (data) => this._onRawReadChanged(data, 'p2p'));
         // V2 P2P 推送通知：收到通知后自动走 message.v2.pull 拉取并解密
         this._dispatcher.subscribeProtocol('_raw.peer.v2.message_received', (data) => {
+            if (this._controlMessages().onPush(data))
+                return;
             const sender = isJsonObject(data) ? String(data.sender_aid ?? '') : '';
             const ns = this._p2pPeerPullEnabled ? (sender ? this._delivery.peerNamespace(sender) : '') : this._aid ? `p2p:${this._aid}` : '';
             const hasInline = isJsonObject(data)
@@ -1111,6 +1161,8 @@ export class AUNClient {
         });
         // V2 群组消息推送通知：收到通知后自动走 group.v2.pull 拉取并解密
         this._dispatcher.subscribeProtocol('_raw.group.v2.message_created', (data) => {
+            if (this._controlMessages().onPush(data, true))
+                return;
             const groupId = isJsonObject(data)
                 ? String(data.group_id ?? '').trim()
                 : '';
@@ -1291,7 +1343,9 @@ export class AUNClient {
     async releaseSubaid(subAid) { return this._getOwnershipWorkflow().releaseSubaid(subAid); }
     async transferSubaid(subAid, newOwnerAid) { return this._getOwnershipWorkflow().transferSubaid(subAid, newOwnerAid); }
     async checkOwnershipConsensus(subAid) {
-        return this._createOwnershipFiles((aid) => this._agentMdManager._readOwnershipQuery(aid)).checkConsensus(ownershipAid(subAid ?? this._aid, 'sub_aid'));
+        const target = ownershipAid(subAid ?? this._aid, 'sub_aid');
+        const result = await this._createOwnershipFiles((aid) => this._agentMdManager._readOwnershipQuery(aid)).checkConsensus(target);
+        return result.status === 'consensus' ? result : this._checkOwnershipConsensusFresh(target);
     }
     async _checkOwnershipConsensusFresh(subAid) {
         return this._getOwnershipWorkflow().checkOwnershipConsensus(subAid);
@@ -1391,6 +1445,12 @@ export class AUNClient {
         return session.aid === this._aid && session.deviceId === this._deviceId;
     }
     _resetV2IdentityRuntime() {
+        this._controlMessageCoordinator?.close();
+        this._agentMdChanges?.close();
+        this._agentMdChanges = undefined;
+        this._negotiatedCapabilities = {};
+        this._riskNegotiated = false;
+        this._riskRestoredAid = '';
         this._v2RuntimeGeneration += 1;
         const keyStore = this._v2KeyStore;
         try {
@@ -1506,6 +1566,7 @@ export class AUNClient {
             fetchEntityIdentity: (target, type) => this._freshEntityCertificate(target, type),
             fetchEntitySigner: (target, fingerprint) => this._freshEntitySigner(target, fingerprint),
         });
+        this._installAgentMdChangeHooks();
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: 35_000,
@@ -1513,6 +1574,8 @@ export class AUNClient {
             logger: this._logger.for('aun_core.transport'),
             dnsNet,
         });
+        this._installRiskHooks();
+        this._transport.setClassMessageHandler((event, payload) => this._controlMessages().onPush(payload, event.includes('group.')));
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
         this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
@@ -1616,6 +1679,7 @@ export class AUNClient {
     }
     /** 关闭连接 */
     async close() {
+        this._risk.close();
         this._peerGatewayCache.clear();
         return this._lifecycle.close();
     }
@@ -1626,6 +1690,155 @@ export class AUNClient {
     async disconnect() {
         return this._lifecycle.disconnect();
     }
+    get riskState() { return Object.freeze(structuredClone(this._risk.state)); }
+    _installRiskHooks() {
+        this._transport.setRiskControlHandler((payload) => this._onRiskControl(payload));
+        this._transport.setRequestAdmission((request) => this._risk.acquire(request));
+        this._transport.setRequestCheck((request) => this._risk.check(request));
+        this._auth.setRequestAdmission((request) => this._risk.acquire(request));
+        this._auth.setRiskSupport(() => this._gatewayUrl?.startsWith('wss://') === true);
+        this._auth.setHttpHandler((url, init, perform) => this._riskFetch(url, init, perform, 'http:gateway:pki'));
+        this._discovery.setHttpHandler((url, init, perform) => this._riskFetch(url, init, perform, new URL(url).pathname === '/health' ? 'http:gateway:health' : 'http:discovery:gateway'));
+        const aid = this._aid;
+        if (aid)
+            this._aidStore?.setRiskController(aid, async () => {
+                if (this._aid !== aid || this._deviceId !== this._aidStore?.deviceId)
+                    return null;
+                await this._restoreRiskState();
+                return this._risk.appliesTo(aid, this._deviceId) ? this._risk : null;
+            });
+        this._agentMdManager.setHttpHandler((url, init, perform) => {
+            const headers = new Headers(init.headers);
+            const scope = headers.has('X-AUN-Ownership-Check') || headers.has('X-AUN-Ownership-Stage') ? 'http:nameservice:ownership' : 'http:nameservice:agent_md';
+            return this._riskFetch(url, init, perform, scope);
+        });
+    }
+    async _restoreRiskState() {
+        const aid = this._aid;
+        if (!aid || this._riskRestoredAid === aid)
+            return;
+        this._risk.reset();
+        this._riskHttpRetryAt.clear();
+        this._riskScalarReconnectAt = 0;
+        const raw = this._tokenStore.loadMetadata?.(aid)?.[`risk_state_v1:${this._deviceId}`];
+        if (raw) {
+            try {
+                const state = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                if (!isJsonObject(state) || !isJsonObject(state.target) || state.target.aid !== aid || state.target.device_id !== this._deviceId || !isJsonObject(state.signing_keys))
+                    throw new Error('risk state invalid');
+                const [keyId, key] = Object.entries(state.signing_keys)[0] ?? [];
+                if (!keyId || !Array.isArray(key))
+                    throw new Error('risk signing key unavailable');
+                this._risk.configure({ aid, device_id: this._deviceId, slot_id: this._slotId, connection_id: '' }, { key_id: keyId, public_key: Buffer.from(key).toString('base64url'), algorithm: 'ECDSA-P256-SHA256' }, Number(state.server_time_ms));
+                await this._risk.restore(state);
+            }
+            catch {
+                throw new StateError('persisted risk state could not be verified', { stringCode: 'risk_state_unavailable', retryable: true });
+            }
+        }
+        this._riskRestoredAid = aid;
+    }
+    _assertRiskReconnect() {
+        const delay = this._riskReconnectDelay();
+        if (delay > 0)
+            throw new ConnectionError('connection postponed by risk policy', { stringCode: 'risk_restricted', retryable: true, data: { retry_after_ms: Math.ceil(delay) } });
+    }
+    _riskReconnectDelay() { return Math.max(this._risk.reconnectDelayMs(), this._riskScalarReconnectAt - (typeof performance !== 'undefined' ? performance.now() : Date.now()), 0); }
+    async _applyRiskHello(hello) {
+        this._riskNegotiated = false;
+        if (!isJsonObject(hello.negotiated_capabilities) || hello.negotiated_capabilities.risk_test_v1 !== true)
+            return;
+        if (!this._gatewayUrl?.startsWith('wss://') || !this._configModel.verifySsl || !this._aid || !isJsonObject(hello.risk_signing_key))
+            return;
+        const key = hello.risk_signing_key;
+        const initial = isJsonObject(hello.risk_state) ? hello.risk_state : {};
+        this._risk.configure({ aid: this._aid, device_id: this._deviceId, slot_id: this._slotId, connection_id: this._gatewayConnectionId }, { key_id: String(key.key_id ?? ''), public_key: String(key.public_key ?? ''), algorithm: String(key.algorithm ?? '') }, Number(hello.server_time_ms ?? initial.server_time_ms));
+        this._riskNegotiated = true;
+        await this._transport.setRiskSnapshot(this._risk.exportState(true));
+        if (Array.isArray(initial.states))
+            for (const state of initial.states)
+                if (isJsonObject(state))
+                    await this._onRiskControl(state);
+    }
+    async _onRiskControl(payload) {
+        const identity = JSON.stringify([this._aid, this._deviceId, this._slotId, this._serviceEventIdentityVersion, this._transport._connectionGeneration]);
+        const run = this._riskApplyTail.then(async () => {
+            const current = () => identity === JSON.stringify([this._aid, this._deviceId, this._slotId, this._serviceEventIdentityVersion, this._transport._connectionGeneration]);
+            if (current())
+                await this._applyRiskControl(payload, current);
+        });
+        this._riskApplyTail = run.catch(() => { });
+        await run;
+    }
+    async _applyRiskControl(payload, current) {
+        if (!this._riskNegotiated)
+            return;
+        this._riskApplying = true;
+        let status;
+        try {
+            status = await this._risk.apply(payload);
+        }
+        catch {
+            this._riskApplying = false;
+            this._riskEvents = [];
+            return;
+        }
+        this._riskApplying = false;
+        await this._transport.setRiskSnapshot(this._risk.exportState(true));
+        if (!current()) {
+            this._riskEvents = [];
+            return;
+        }
+        const params = { version: 1, delivery_id: payload.delivery_id, subject: payload.subject, revision: payload.revision, status: this._risk.persistenceFailed ? 'failed' : status };
+        if (this._risk.persistenceFailed)
+            params.error_code = 'persistence_unavailable';
+        const acknowledgement = this._transport.call('gateway.risk_ack', params, 500).catch(() => { });
+        for (const event of this._riskEvents.splice(0))
+            this._dispatcher.enqueue('risk_state_changed', event);
+        if (this._risk.shouldDisconnect()) {
+            await acknowledgement;
+            if (current())
+                void this._handleTransportDisconnect(new ConnectionError('connection restricted by risk policy', { code: 4029, stringCode: 'risk_restricted', retryable: true }), 4029);
+        }
+    }
+    async _riskFetch(input, init = {}, perform = fetch, requestScope) {
+        await this._restoreRiskState();
+        const url = new URL(input);
+        const route = `${url.origin}${url.pathname}`;
+        const monotonicNow = () => typeof performance !== 'undefined' ? performance.now() : Date.now();
+        const retryAt = this._riskHttpRetryAt.get(route) ?? 0;
+        if (retryAt > monotonicNow())
+            throw new StateError('HTTP request postponed by risk response', { stringCode: 'risk_restricted', retryable: true, data: { retry_after_ms: Math.ceil(retryAt - monotonicNow()) } });
+        const release = this._risk.acquire(requestScope ?? (['GET', 'HEAD'].includes(String(init.method ?? 'GET').toUpperCase()) ? 'http:storage:read' : 'http:storage:write'));
+        try {
+            const response = await perform(input, init);
+            if (response.status === 429) {
+                try {
+                    const body = await response.clone().json();
+                    const detail = isJsonObject(body) && isJsonObject(body.error) && isJsonObject(body.error.data) ? body.error.data : isJsonObject(body) && isJsonObject(body.data) ? body.data : isJsonObject(body) ? body : {};
+                    const wrapper = detail.risk_state;
+                    if (this._riskNegotiated && isJsonObject(wrapper) && Array.isArray(wrapper.states))
+                        for (const state of wrapper.states)
+                            if (isJsonObject(state))
+                                await this._onRiskControl(state);
+                    const delayMs = Number(detail.retry_after_ms);
+                    if (Number.isSafeInteger(delayMs) && delayMs > 0)
+                        this._riskHttpRetryAt.set(route, monotonicNow() + delayMs);
+                }
+                catch { /* 无签名状态的 HTTP 错误由调用入口处理 */ }
+                const header = response.headers.get('Retry-After');
+                if (header) {
+                    const delayMs = /^\d+$/.test(header) ? Number(header) * 1000 : Math.max(0, Date.parse(header) - Date.now());
+                    if (Number.isFinite(delayMs) && delayMs > 0)
+                        this._riskHttpRetryAt.set(route, Math.max(this._riskHttpRetryAt.get(route) ?? 0, monotonicNow() + delayMs));
+                }
+            }
+            return response;
+        }
+        finally {
+            release();
+        }
+    }
     // ── RPC ───────────────────────────────────────────────────
     /**
      * 发送 JSON-RPC 调用。
@@ -2783,6 +2996,10 @@ export class AUNClient {
         const messageEvent = event === 'message.received' || event === 'message.recalled' || event === 'message.batch';
         const hadMessageConsumer = messageEvent && [...this._dispatcher._snapshotApplicationHandlers(['message.received', 'message.recalled', 'message.batch']).values()].some((handlers) => handlers.length > 0);
         const result = this._dispatcher.subscribe(event, handler);
+        if (event === 'agent_md_changed') {
+            this._getAgentMdChanges().schedule();
+            void this._getAgentMdChanges().deliverEvents().catch((error) => this._clientLog.debug(String(error)));
+        }
         if (messageEvent) {
             if (this._p2pPeerPullEnabled && !hadMessageConsumer)
                 this._delivery.refreshPendingPeers();
@@ -3020,6 +3237,8 @@ export class AUNClient {
     // ── 事件自动解密管线 ──────────────────────────────────────
     /** 处理 transport 层推送的原始 P2P 消息 */
     async _onRawMessageReceived(data) {
+        if (this._controlMessages().onPush(data))
+            return;
         return this._delivery.onRawMessageReceived(data);
     }
     async _onRawMessageRecalled(data) {
@@ -3027,6 +3246,8 @@ export class AUNClient {
     }
     /** 处理群组消息推送：自动解密后 re-publish */
     async _onRawGroupMessageCreated(data) {
+        if (this._controlMessages().onPush(data, true))
+            return;
         return this._delivery.onRawGroupMessageCreated(data);
     }
     async _onRawGroupMessageRecalled(data) {
@@ -3114,6 +3335,8 @@ export class AUNClient {
         this._delivery.markPublishedSeq(ns, seq);
     }
     _publishAppEvent(event, payload, source = 'direct', deliveryContext) {
+        if (messageClassOf(payload) === 'sdk_control')
+            return this._controlMessages().consume(payload);
         if (event === 'message.received') {
             return this._handleOwnershipMessage(payload).then((handled) => {
                 if (!handled)
@@ -3596,7 +3819,7 @@ export class AUNClient {
                     throw new ValidationError('gateway url unavailable for e2ee cert fetch');
                 }
                 const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
-                const certPem = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint), this._configModel.verifySsl, timeoutMs);
+                const certPem = await this._auth._fetchRiskText(AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint));
                 if (auth !== this._auth || pkiEpoch !== auth._strictPkiEpoch)
                     throw new ValidationError('peer certificate fetch context changed');
                 const validated = await this._validateAndCachePeerCert({
@@ -4037,6 +4260,9 @@ export class AUNClient {
     // ── 内部：连接 ────────────────────────────────────────────
     /** 执行一次连接流程 */
     async _connectOnce(params, allowReauth, reconnectOwner, connectionOwner) {
+        await this._restoreRiskState();
+        this._assertRiskReconnect();
+        this._riskNegotiated = false;
         const tStart = Date.now();
         connectionOwner ??= this._connectAbort ?? undefined;
         this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
@@ -4046,8 +4272,15 @@ export class AUNClient {
         this._captureCapabilitiesFromConnect(params);
         this._connectDeliveryMode = { ...(params.delivery_mode ?? this._connectDeliveryMode) };
         const extraInfo = (params.extra_info && typeof params.extra_info === 'object' && !Array.isArray(params.extra_info))
-            ? params.extra_info
-            : undefined;
+            ? { ...params.extra_info }
+            : {};
+        if (typeof this._tokenStore.updateInstanceState === 'function') {
+            extraInfo._capabilities = {
+                ...(isJsonObject(extraInfo._capabilities) ? extraInfo._capabilities : {}),
+                message_classes_v1: { p2p: ['normal', 'control', 'sdk_control'], group: ['normal', 'control', 'sdk_control'] },
+                sdk_control_protocols: { 'aun.agent_md.changed': [1] },
+            };
+        }
         const prevState = this._state;
         this._auth.setInstanceContext({ deviceId: this._deviceId, slotId: this._slotId });
         this._state = 'connecting';
@@ -4097,6 +4330,9 @@ export class AUNClient {
                         this._applyServerHeartbeatInterval(auth.hello.heartbeat_interval, 'auth');
                     }
                     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 : {};
+                    if (isJsonObject(auth.hello))
+                        await this._applyRiskHello(auth.hello);
                 }
             }
             else {
@@ -4115,6 +4351,9 @@ export class AUNClient {
                     this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
                 }
                 this._gatewayConnectionId = isJsonObject(hello) && isJsonObject(hello.connection) ? String(hello.connection.id ?? '') : '';
+                this._negotiatedCapabilities = isJsonObject(hello) && isJsonObject(hello.negotiated_capabilities) ? hello.negotiated_capabilities : {};
+                if (isJsonObject(hello))
+                    await this._applyRiskHello(hello);
             }
             this._assertReconnectOwner(reconnectOwner);
             this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
@@ -4178,6 +4417,11 @@ export class AUNClient {
             else {
                 this._clientLog.debug('V2 session init deferred for short connection');
             }
+            this._controlMessages().close();
+            this._safeAsync(this._controlMessages().recover());
+            this._agentMdChanges?.close();
+            this._agentMdChanges = new AgentMdChangeCoordinator(this);
+            this._agentMdChanges.schedule();
             // connect/reconnect 成功后自动触发一次 P2P message.v2.pull，补齐离线期间积压
             // 群消息按惰性触发，不在此处主动 pull
             if (backgroundSyncEnabled) {
@@ -4415,6 +4659,8 @@ export class AUNClient {
             this._clientLog.warn(`V2 decrypt: invalid envelope_json for msg seq=${String(msg.seq)}`);
             return null;
         }
+        if (messageClassOf({ ...msg, envelope }) === 'sdk_control' && source !== 'control_pull')
+            return null;
         const e2eeMeta = this._v2E2eeMeta(envelope);
         if (observeAgentMd) {
             if (deferredEffects)
@@ -4808,6 +5054,8 @@ export class AUNClient {
         return this._groupState.autoConfirmPendingProposals();
     }
     async _onV2PushNotification(data, expectedVersion, inlineGeneration) {
+        if (this._controlMessages().onPush(data))
+            return;
         return this._delivery.onV2PushNotification(data, expectedVersion, inlineGeneration);
     }
     async _onV2StateProposed(data) {
@@ -4820,6 +5068,8 @@ export class AUNClient {
         return this._groupState.onV2StateConfirmed(data);
     }
     async _onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration) {
+        if (this._controlMessages().onPush(data, true))
+            return;
         return this._delivery.onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration);
     }
     /** Push 通知带 payload 时的就地解密（复用 _decryptV2Message） */
@@ -5417,15 +5667,25 @@ export class AUNClient {
      * 透传到应用层可订阅事件 'gateway.disconnect'，方便业务定位被踢原因。
      */
     async _onGatewayDisconnect(data) {
-        const payload = (data && typeof data === 'object') ? data : {};
+        const payload = (data && typeof data === 'object') ? structuredClone(data) : {};
         const code = payload.code;
         const reason = payload.reason ?? '';
         const detail = (payload.detail && typeof payload.detail === 'object' && !Array.isArray(payload.detail))
             ? payload.detail
             : {};
+        const wrapper = payload.risk_state ?? detail.risk_state;
+        delete payload.risk_state;
+        delete detail.risk_state;
+        if (isJsonObject(wrapper) && Array.isArray(wrapper.states))
+            for (const state of wrapper.states)
+                if (isJsonObject(state))
+                    await this._onRiskControl(state);
+        const retryMs = Number(detail.retry_after_ms ?? payload.retry_after_ms ?? 0);
+        if (Number(code) === 4029 && Number.isSafeInteger(retryMs) && retryMs > 0)
+            this._riskScalarReconnectAt = (typeof performance !== 'undefined' ? performance.now() : Date.now()) + retryMs;
         this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}, detail=${JSON.stringify(detail)}`);
         const reasonText = String(reason ?? '').trim().toLowerCase();
-        const retryable = Number(code) === 4012
+        const retryable = Number(code) === 4012 || Number(code) === 4029
             || reasonText.includes('long_connection_already_exists')
             || reasonText.includes('long connection already exists');
         this._serverKicked = !retryable;
@@ -5638,7 +5898,7 @@ export class AUNClient {
                 break;
             }
             this._retryAttempt = attempt;
-            this._nextRetryAt = Date.now() + reconnectSleepDelayMs(delay, maxBaseDelay);
+            this._nextRetryAt = Date.now() + Math.max(reconnectSleepDelayMs(delay, maxBaseDelay), this._riskReconnectDelay());
             this._state = 'retry_backoff';
             if (!reconnectAbort || !await this._publishReconnectEvent(reconnectAbort, 'state_change', {
                 state: this._publicState(this._state),