@agentunion/fastaun 0.5.27 → 0.5.29

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';
@@ -48,7 +51,7 @@ import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
 import { certFingerprint, certMatchesFingerprint, normalizeFingerprintHex, publicKeyMatchesFingerprint } from './cert-utils.js';
 import { validateAgentMdCertificate, validateAgentMdDocument } from './agent-md-schema.js';
-import { OwnershipFiles, OwnershipStorageAdapter, ownershipAid, ownershipFailure } from './ownership-v21.js';
+import { OwnershipFiles, OwnershipStorageAdapter, ownershipAid, ownershipFailure, ownershipSha256, parseOwnershipFile } from './ownership-v21.js';
 import { OwnershipWorkflow, OWNERSHIP_SDK_MESSAGE_TYPE, parseOwnershipMessage } from './ownership-workflow.js';
 import { canonicalJson, createCredential, createMemberCredential, signMembershipBinding, digest, validateMembershipBinding, verifyMembershipBinding, verifyCredentialSignature, createRepresentationProof, verifyServiceEvent, buildRequestBinding, validateRequestBinding, CredentialRenewal } from './org-protocol.js';
 import { SemanticProtocolError } from './semantic-protocol.js';
@@ -342,7 +345,7 @@ function createAgentMdManagerForRuntime(opts) {
     return new AgentMdManager({
         aunPath: opts.config().aunPath,
         verifySsl: opts.config().verifySsl,
-        onChanged: (aid) => opts.dispatcher().enqueue('agentmd.changed', aid),
+        onChanged: (aid) => opts.dispatcher().enqueue('agentmd.changed', { aid }),
         discoveryPort: opts.config().discoveryPort,
         uploadViaGatewayHost: true,
         logger: opts.logger(),
@@ -486,6 +489,7 @@ export class AUNClient {
     _ownershipStorage = null;
     _ownershipFiles = null;
     _ownershipWorkflow = null;
+    _ownershipConsensusCache = new Map();
     _getOwnershipStorage() {
         return this._ownershipStorage ??= new OwnershipStorageAdapter({ currentAid: () => this._aid, call: (method, params) => this.call(method, params), httpPut: (url, data, headers) => this.storage.lowlevel.httpPut(url, data, headers) });
     }
@@ -497,6 +501,10 @@ export class AUNClient {
             currentAid: () => { if (!this._currentAid)
                 throw ownershipFailure('forbidden', 'ownership requires a loaded identity'); return this._currentAid; },
             currentType: () => this.getType(),
+            currentExttype: () => {
+                const metadata = this._tokenStore.loadMetadata?.(String(this._aid ?? ''));
+                return String(metadata?.identity_exttype ?? metadata?.registration_intent?.exttype ?? '');
+            },
             now: () => Math.trunc(Date.now() / 1000),
             readAgentMdFresh,
             submitAgentMdRaw: (subAid, raw, condition, assertActive, stage) => this._agentMdManager.submitOwnershipRaw(subAid, raw, condition, assertActive, stage),
@@ -512,40 +520,59 @@ export class AUNClient {
             currentType: () => this.getType(), assertCurrent: () => this._ownershipOperationGuard?.(),
             recoverRequest: (operationId) => this._recoverOwnershipRequest(operationId),
             send: (to, payload, messageId) => this.call('message.send', { to, encrypt: true, message_id: messageId, payload: payload }),
-            emit: (event, payload) => this._dispatcher.enqueue(event, payload),
+            emit: (event, payload) => { this._ownershipConsensusCache = new Map(); this._dispatcher.enqueue(event, payload); },
         });
     }
     async _recoverOwnershipRequest(operationId) {
         const identity = this._aid, version = this._serviceEventIdentityVersion;
         const current = () => { if (this._aid !== identity || this._serviceEventIdentityVersion !== version)
             throw ownershipFailure('conflict', 'ownership request identity changed'); };
-        const catalog = await this.call('message.peers', { filter: 'all', limit: 200 });
-        current();
-        for (const peer of Array.isArray(catalog.peers) ? catalog.peers.slice(0, 200) : []) {
-            const sender = String(peer.sender_aid ?? '');
-            const history = await this.call('message.history', { sender_aid: sender, before_seq: Number.MAX_SAFE_INTEGER, limit: 200 });
+        const query = { filter: 'all', limit: 200 }, tokens = new Set();
+        for (;;) {
+            const catalog = await this.call('message.peers', query);
             current();
-            for (const row of Array.isArray(history.messages) ? history.messages : []) {
-                const envelope = row, content = envelope.payload ?? envelope;
-                const raw = decryptedOwnershipJsonText(content) ?? content;
-                let value = raw;
-                if (typeof raw === 'string') {
-                    try {
-                        value = JSON.parse(raw);
-                    }
-                    catch {
-                        continue;
+            for (const peer of Array.isArray(catalog.peers) ? catalog.peers : []) {
+                const sender = String(peer.sender_aid ?? ''), head = Number(peer.head_seq);
+                const snapshot = Number.isSafeInteger(head) && head > 0 && head < Number.MAX_SAFE_INTEGER ? { snapshot_head_seq: head } : {};
+                let before = snapshot.snapshot_head_seq === undefined ? Number.MAX_SAFE_INTEGER : head + 1;
+                for (;;) {
+                    const history = await this.call('message.history', { sender_aid: sender, before_seq: before, ...snapshot, limit: 200 });
+                    current();
+                    for (const row of Array.isArray(history.messages) ? history.messages : []) {
+                        const envelope = row, content = envelope.payload ?? envelope;
+                        const raw = decryptedOwnershipJsonText(content) ?? content;
+                        let value = raw;
+                        if (typeof raw === 'string') {
+                            try {
+                                value = JSON.parse(raw);
+                            }
+                            catch {
+                                continue;
+                            }
+                        }
+                        if (!isJsonObject(value) || value.type !== OWNERSHIP_SDK_MESSAGE_TYPE || value.operation_id !== operationId || !['bind.request', 'transfer.request'].includes(String(value.action)))
+                            continue;
+                        const authenticated = String(envelope.from_aid ?? envelope.from ?? envelope.sender_aid ?? '');
+                        if (authenticated !== sender)
+                            throw ownershipFailure('forbidden', 'ownership history sender changed');
+                        return { from: authenticated, payload: parseOwnershipMessage(raw, { authenticated_from_aid: authenticated, local_aid: identity }) };
                     }
+                    if (history.has_older !== true)
+                        break;
+                    const next = Number(history.next_before_seq);
+                    if (!Number.isSafeInteger(next) || next <= 0 || next >= before)
+                        throw ownershipFailure('unavailable', 'ownership history pagination did not advance');
+                    before = next;
                 }
-                if (!isJsonObject(value) || value.type !== OWNERSHIP_SDK_MESSAGE_TYPE || value.operation_id !== operationId || !['bind.request', 'transfer.request'].includes(String(value.action)))
-                    continue;
-                const authenticated = String(envelope.from_aid ?? envelope.from ?? envelope.sender_aid ?? '');
-                if (authenticated !== sender)
-                    throw ownershipFailure('forbidden', 'ownership history sender changed');
-                return { from: authenticated, payload: parseOwnershipMessage(raw, { authenticated_from_aid: authenticated, local_aid: identity }) };
             }
+            if (catalog.has_more !== true)
+                return null;
+            const token = catalog.next_page_token;
+            if (typeof token !== 'string' || !token || tokens.has(token))
+                throw ownershipFailure('unavailable', 'peer directory pagination did not advance');
+            tokens.add(token);
+            query.page_token = token;
         }
-        return null;
     }
     _restoreIdentityType() {
         const aid = String(this._aid ?? '').trim();
@@ -929,6 +956,20 @@ export class AUNClient {
     _v2KeyStore;
     _v2SessionInitInFlight = null;
     _v2RuntimeGeneration = 0;
+    _controlMessageCoordinator;
+    _agentMdChanges;
+    _installAgentMdChangeHooks() {
+        this._agentMdManager.setOnCommitted((aid, notice) => this._getAgentMdChanges().committed(aid, notice));
+    }
+    _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 +990,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;
@@ -1021,6 +1083,7 @@ export class AUNClient {
         this._ownershipStorage = null;
         this._ownershipFiles = null;
         this._ownershipWorkflow = null;
+        this._ownershipConsensusCache = new Map();
         this._slotId = inputAid?.slotId || 'default';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -1059,6 +1122,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 +1130,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 +1166,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 +1179,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()
                 : '';
@@ -1290,11 +1360,48 @@ 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'));
+    async checkOwnershipConsensus(subAid, force = false) {
+        const target = ownershipAid(subAid ?? this._aid, 'sub_aid');
+        const record = this._agentMdManager.loadRecord(target);
+        const observedEtag = String(record?.remote_etag ?? '');
+        const cache = this._ownershipConsensusCache ??= new Map();
+        const cached = cache.get(target);
+        if (!force && cached?.result.status === 'consensus' && record?.remote_status !== 'missing'
+            && (observedEtag === cached.observedEtag || observedEtag === cached.result.agent_md_etag)) {
+            cached.observedEtag = observedEtag;
+            return { ...cached.result };
+        }
+        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 } };
+        cache.set(target, entry);
+        try {
+            const snapshot = await this._agentMdManager.readOwnershipFresh(target);
+            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)
+                result.ownership_status = snapshot.ownership_status;
+            const statement = snapshot.exists ? parseOwnershipFile(snapshot.content, 'agent', { expectedSubAid: target }).statement : undefined;
+            if (snapshot.relation_version !== (statement?.relation_version ?? 0) || snapshot.lock === 'locked' && !statement
+                || snapshot.ownership_status === 'pending' && snapshot.lock !== 'unlocked')
+                throw ownershipFailure('unavailable', 'NS relationship metadata does not match agent.md', true);
+            result.status = snapshot.ownership_status === 'pending' ? 'single_sided' : statement ? snapshot.lock === 'locked' ? 'consensus' : 'released' : 'unbound';
+            result.owner_aid = result.status === 'consensus' ? statement.owner_aid : null;
+        }
+        catch (error) {
+            const code = error instanceof StateError && error.stringCode ? error.stringCode : error instanceof ValidationError ? 'invalid' : 'unavailable';
+            result.status = code === 'not_applicable' ? 'not_applicable' : code === 'invalid' ? 'invalid' : 'unavailable';
+            result.owner_aid = null;
+            result.code = code;
+            result.reason = error instanceof Error ? error.message : String(error);
+            result.retryable = result.status === 'unavailable';
+        }
+        if (cache.get(target) === entry)
+            entry.result = { ...result };
+        return result;
     }
     async _checkOwnershipConsensusFresh(subAid) {
-        return this._getOwnershipWorkflow().checkOwnershipConsensus(subAid);
+        return this.checkOwnershipConsensus(subAid, true);
     }
     async bindAid(subjectAid, options = {}) {
         throw ownershipFailure('unsupported_protocol', 'legacy bindAid is unsupported; use bindSubaid');
@@ -1391,6 +1498,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 {
@@ -1473,6 +1586,7 @@ export class AUNClient {
         this._ownershipStorage = null;
         this._ownershipFiles = null;
         this._ownershipWorkflow = null;
+        this._ownershipConsensusCache = new Map();
         this._auth = new AuthFlow({
             tokenStore,
             crypto: new CryptoProvider(),
@@ -1506,6 +1620,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 +1628,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 +1733,7 @@ export class AUNClient {
     }
     /** 关闭连接 */
     async close() {
+        this._risk.close();
         this._peerGatewayCache.clear();
         return this._lifecycle.close();
     }
@@ -1626,6 +1744,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 调用。
@@ -1708,7 +1975,7 @@ export class AUNClient {
     }
     async _ensureInitialAgentMd() {
         const aid = this._aid;
-        if (!aid || !this._currentAid)
+        if (!aid || !this._currentAid || this.getType() !== 'human')
             return false;
         const observed = await this._agentMdManager.readAgentMdFresh(aid);
         if (observed.exists || String(this._agentMdManager._loadRecord?.(aid, true)?.local_draft_content ?? this._agentMdManager.loadRecord(aid)?.local_draft_content ?? '') || this._agentMdManager.pendingUpload(aid))
@@ -1859,7 +2126,7 @@ export class AUNClient {
         this._aidStore = store;
         let identity = store.load(orgAid);
         if (!identity.ok) {
-            const registered = await store.register(orgAid, { type: 'org', owner: owner.aid });
+            const registered = await store._registerIdentity(orgAid, { type: 'org', owner: owner.aid, exttype: String(params.exttype ?? '') });
             if (!registered.ok)
                 throw ownershipFailure('unavailable', registered.error.message, true);
             identity = store.load(orgAid);
@@ -2077,7 +2344,7 @@ export class AUNClient {
             return;
         const identity = this._localEntityCertificate(orgAid);
         const content = String(params.org_agent_md ?? buildDefaultAgentMd(orgAid, { type: 'org', owner: owner.aid, entityCertFingerprint: identity.certFingerprint, name: String(params.name ?? orgAid) }));
-        const uploaded = await store.uploadAgentMd(orgAid, content, { uploaderAid: owner.aid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid, 'org') });
+        const uploaded = await store._uploadAgentMd(orgAid, content, { uploaderAid: owner.aid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid, 'org') }, (aid, notice, manager) => this._getAgentMdChanges().committed(aid, notice, manager));
         if (!uploaded.ok) {
             const code = ['invalid', 'unavailable', 'forbidden', 'conflict', 'persistence_unavailable'].includes(uploaded.error.code) ? uploaded.error.code : uploaded.error.code === 'NETWORK_ERROR' ? 'unavailable' : 'invalid';
             throw ownershipFailure(code, uploaded.error.message, code === 'unavailable');
@@ -2278,6 +2545,7 @@ export class AUNClient {
             aunPath: store.aunPath,
             verifySsl: identityStore._verifySsl,
             logger: identityStore._log.for('aun_core.agent_md'),
+            onCommitted: (aid, notice) => this._getAgentMdChanges().committed(aid, notice, manager),
             uploadViaGatewayHost: true,
             ownerAidGetter: () => identity.aid,
             currentAidGetter: () => identity,
@@ -2305,7 +2573,7 @@ export class AUNClient {
         const bootstrap = initialCertificate ? { aid: groupAid, ownerAid: String(group.owner_aid ?? '').trim(), certFingerprint: certFingerprint(initialCertificate), type: 'group' } : undefined;
         if (await this._resumeGroupAgentMdUpload(store, groupAid, bootstrap))
             return;
-        const uploaded = await store.uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid) });
+        const uploaded = await store._uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid) }, (aid, notice, manager) => this._getAgentMdChanges().committed(aid, notice, manager));
         if (!uploaded.ok) {
             const code = ['invalid', 'unavailable', 'forbidden', 'conflict', 'persistence_unavailable'].includes(uploaded.error.code) ? uploaded.error.code : uploaded.error.code === 'NETWORK_ERROR' ? 'unavailable' : 'invalid';
             throw ownershipFailure(code, `group agent.md upload failed: ${uploaded.error.message}`, code === 'unavailable');
@@ -3020,6 +3288,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 +3297,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 +3386,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 +3870,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 +4311,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 +4323,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 +4381,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 +4402,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 +4468,10 @@ 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);
             // connect/reconnect 成功后自动触发一次 P2P message.v2.pull，补齐离线期间积压
             // 群消息按惰性触发，不在此处主动 pull
             if (backgroundSyncEnabled) {
@@ -4415,6 +4709,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 +5104,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 +5118,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 +5717,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 +5948,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),