@agentunion/fastaun-browser 0.4.5 → 0.4.6

package/dist/client.js

@@ -4,7 +4,7 @@
 //   - HTTP 使用 fetch() 而非 Node http
 //   - 无文件系统（IndexedDB via keystore）
 //   - 后台任务使用 setTimeout/setInterval
-import { createConfig, getDeviceId, normalizeInstanceId, normalizeSlotId, slotIsolationKey } from './config.js';
+import { createConfig, getDeviceId, normalizeSlotId, slotIsolationKey } from './config.js';
 import { EventDispatcher } from './events.js';
 import { normalizeGroupId } from './group-id.js';
 import { GatewayDiscovery } from './discovery.js';
@@ -12,12 +12,13 @@ import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
 import { CryptoProvider, uint8ToBase64, base64ToUint8, pemToArrayBuffer, p1363ToDer, certificateSha256Fingerprint, ecdsaSignDer, ecdsaVerifyDer, importCertPublicKeyEcdsa, importPrivateKeyEcdsa, } from './crypto.js';
-import { IndexedDBKeyStore } from './keystore/indexeddb.js';
+import { IndexedDBTokenStore } from './keystore/indexeddb-token-store.js';
 import { V2Session, V2KeyStore } from './v2/session/index.js';
 import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2ee/index.js';
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { computeStateCommitment } from './v2/state/index.js';
 import { AUNLogger } from './logger.js';
+import { AgentMdManager } from './agent-md.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, ValidationError, } from './errors.js';
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
@@ -239,7 +240,6 @@ function reconnectSleepDelaySeconds(baseDelay, maxBaseDelay) {
 /** 对端证书缓存 TTL（秒） */
 const PEER_CERT_CACHE_TTL = 3600;
 const PEER_PREKEYS_CACHE_TTL = 3600;
-const AGENT_MD_HTTP_TIMEOUT_MS = 30_000;
 /**
  * 将 WebSocket URL 转为对应的 HTTP URL
  */
@@ -272,28 +272,89 @@ function buildCertUrl(gatewayUrl, aid, certFingerprint) {
     }
     return url.toString();
 }
-function agentMdHttpScheme(gatewayUrl) {
-    const raw = String(gatewayUrl ?? '').trim().toLowerCase();
-    return raw.startsWith('ws://') ? 'http' : 'https';
-}
-function agentMdAuthority(aid) {
-    return String(aid ?? '').trim();
-}
-async function fetchWithTimeout(input, init, timeoutMs = AGENT_MD_HTTP_TIMEOUT_MS) {
-    const controller = new AbortController();
-    const timer = globalThis.setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        return await fetch(input, { ...init, signal: controller.signal });
-    }
-    catch (error) {
-        if (controller.signal.aborted) {
-            throw new AUNError(`agent.md request timed out after ${timeoutMs}ms`);
-        }
-        throw error;
-    }
-    finally {
-        globalThis.clearTimeout(timer);
-    }
+function createAgentMdManagerForRuntime(opts) {
+    return new AgentMdManager({
+        aunPath: opts.config().aunPath,
+        tokenStore: opts.tokenStore(),
+        logger: opts.logger(),
+        ownerAidGetter: opts.ownerAid,
+        currentAidGetter: opts.currentAid,
+        gatewayResolver: async (aid) => {
+            const gatewayUrl = await opts.gateway.resolve(aid);
+            opts.gateway.set(gatewayUrl);
+            return gatewayUrl;
+        },
+        accessTokenResolver: async (aid, gatewayUrl) => {
+            const target = String(aid ?? '').trim();
+            let identity = await opts.auth().loadIdentityOrNone(target);
+            if (!identity && opts.identity.get() && String(opts.identity.get()?.aid ?? '') === target) {
+                identity = opts.identity.get();
+            }
+            if (!identity) {
+                throw new StateError('no local identity found, register or load an AID first');
+            }
+            const auth = opts.auth();
+            const cachedToken = String(identity.access_token ?? '');
+            const expiresAt = auth.getAccessTokenExpiry(identity);
+            if (cachedToken && (expiresAt === null || expiresAt > Date.now() / 1000 + 30)) {
+                return cachedToken;
+            }
+            if (identity.refresh_token) {
+                try {
+                    const refreshed = await auth.refreshCachedTokens(gatewayUrl, identity);
+                    const refreshedToken = String(refreshed.access_token ?? '');
+                    const refreshedExpiry = auth.getAccessTokenExpiry(refreshed);
+                    if (refreshedToken && (refreshedExpiry === null || refreshedExpiry > Date.now() / 1000 + 30)) {
+                        opts.identity.set(refreshed);
+                        return refreshedToken;
+                    }
+                }
+                catch {
+                    // refresh 失败时回退到完整 authenticate。
+                }
+            }
+            const result = await auth.authenticate(gatewayUrl, target);
+            const token = String(result.access_token ?? '');
+            if (!token)
+                throw new StateError('authenticate did not return access_token');
+            const fallbackIdentity = {
+                ...identity,
+                access_token: token,
+                refresh_token: String(result.refresh_token ?? identity.refresh_token ?? ''),
+            };
+            const fallbackExpiresAt = Number(result.expires_at ?? identity.expires_at ?? NaN);
+            if (Number.isFinite(fallbackExpiresAt))
+                fallbackIdentity.expires_at = fallbackExpiresAt;
+            opts.identity.set(await auth.loadIdentityOrNone(target) ?? fallbackIdentity);
+            return token;
+        },
+        peerResolver: async (aid) => {
+            const target = String(aid ?? '').trim();
+            const current = opts.currentAid();
+            if (current?.aid === target)
+                return current;
+            let certPem = String(await opts.tokenStore().loadCert(target) ?? '').trim();
+            if (!certPem) {
+                if (!opts.gateway.get()) {
+                    try {
+                        opts.gateway.set(await opts.gateway.resolve(target));
+                    }
+                    catch { /* best effort */ }
+                }
+                certPem = String(await opts.fetchPeerCert(target) ?? '').trim();
+            }
+            if (!certPem)
+                throw new NotFoundError(`certificate not found for aid: ${target}`);
+            return await AID.create({
+                aid: target,
+                aunPath: opts.config().aunPath,
+                certPem,
+                privateKeyPem: null,
+                certValid: true,
+                privateKeyValid: false,
+            });
+        },
+    });
 }
 /**
  * 跨域时将 Gateway URL 替换为 peer 所在域的 Gateway URL。
@@ -699,20 +760,8 @@ export class AUNClient {
     /** 最近一次已成功确认的 membership_snapshot；相同快照直接跳过。 */
     _v2AutoProposeLastSnapshot = new Map();
     _v2LazyProposeTriggered = new Map();
-    /**
-     * 本地 agent.md 内容对应的 etag（quoted sha256 hex，与服务端 _agent_md_etag 一致）。
-     *
-     * 由 publishAgentMd() / fetchAgentMd(自身 aid) 写入；用于跟服务端 RPC 注入的 _meta.agent_md_etag
-     * 比对，触发"本地未发布到服务端"或"服务端版本更新"的 UI 提示。
-     */
-    _localAgentMdEtag = '';
-    /** gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。 */
-    _remoteAgentMdEtag = '';
-    /** 浏览器侧 AIDs 逻辑根目录，正文映射到 IndexedDB 里的 {aid}/agent.md。 */
-    _agentMdPath = '';
-    _agentMdCache = new Map();
-    _agentMdFetchInflight = new Set();
-    _agentMdLock = Promise.resolve();
+    /** agent.md 运行时管理器，负责上传、下载、缓存和 RPC 元数据观察。 */
+    _agentMdManager;
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -770,7 +819,6 @@ export class AUNClient {
             root_ca_path: this.configModel.rootCaPem,
             seed_password: this.configModel.seedPassword,
         };
-        this._agentMdPath = this._agentMdDefaultRoot();
         this._deviceId = (inputAid?.deviceId) || getDeviceId();
         // Logger 必须最早初始化（其他子模块构造时通过 logger 输出）
         this._logger = new AUNLogger({ debug: _debug, aunPath: this.configModel.aunPath });
@@ -784,7 +832,7 @@ export class AUNClient {
         this._clientLog.info(`AUNClient initialized: debug=${_debug} aunPath=${this.configModel.aunPath} aid=${initAid ?? '-'}`);
         this._dispatcher = new EventDispatcher();
         this._discovery = new GatewayDiscovery();
-        this._tokenStore = new IndexedDBKeyStore({});
+        this._tokenStore = new IndexedDBTokenStore();
         this._slotId = inputAid?.slotId || 'default';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -798,6 +846,24 @@ export class AUNClient {
             verifySsl: this.configModel.verifySsl,
         });
         this._aid = initAid;
+        this._agentMdManager = createAgentMdManagerForRuntime({
+            config: () => this.configModel,
+            logger: () => this._logger.for('aun_core.agent_md'),
+            ownerAid: () => this._aid,
+            currentAid: () => this._currentAid,
+            gateway: {
+                resolve: (target) => this._resolveGatewayForAid(target),
+                get: () => this._gatewayUrl,
+                set: (gatewayUrl) => { this._gatewayUrl = gatewayUrl; },
+            },
+            identity: {
+                get: () => this._identity,
+                set: (identity) => { this._identity = identity; },
+            },
+            auth: () => this._auth,
+            tokenStore: () => this._tokenStore,
+            fetchPeerCert: (target) => this._fetchPeerCert(target),
+        });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: DEFAULT_SESSION_OPTIONS.timeouts.call,
@@ -881,664 +947,15 @@ export class AUNClient {
     get aid() {
         return this._aid;
     }
-    _setAgentMdRoot(root) {
-        const next = String(root ?? '').trim() || this._agentMdDefaultRoot();
-        this._agentMdPath = next;
-        this._agentMdCache.clear();
-        return next;
-    }
-    async _resolveAgentMdUrl(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('agent.md requires non-empty aid');
-        let gatewayUrl = String(this._gatewayUrl ?? '').trim();
-        if (!gatewayUrl) {
-            try {
-                gatewayUrl = await this._resolveGatewayForAid(target);
-            }
-            catch {
-                gatewayUrl = '';
-            }
-        }
-        const authority = agentMdAuthority(target);
-        return `${agentMdHttpScheme(gatewayUrl)}://${authority}/agent.md`;
-    }
-    async _ensureAgentMdUploadToken(aid, gatewayUrl) {
-        let identity = await this._auth.loadIdentityOrNone(aid);
-        if (!identity && this._identity && String(this._identity.aid ?? '') === aid) {
-            identity = this._identity;
-        }
-        if (!identity) {
-            throw new StateError('no local identity found, register or load an AID first');
-        }
-        const cachedToken = String(identity.access_token ?? '');
-        const expiresAt = this._auth.getAccessTokenExpiry(identity);
-        if (cachedToken && (expiresAt === null || expiresAt > Date.now() / 1000 + 30)) {
-            return cachedToken;
-        }
-        if (identity.refresh_token) {
-            try {
-                const refreshed = await this._auth.refreshCachedTokens(gatewayUrl, identity);
-                const refreshedToken = String(refreshed.access_token ?? '');
-                const refreshedExpiry = this._auth.getAccessTokenExpiry(refreshed);
-                if (refreshedToken && (refreshedExpiry === null || refreshedExpiry > Date.now() / 1000 + 30)) {
-                    this._identity = refreshed;
-                    return refreshedToken;
-                }
-            }
-            catch {
-                // refresh 失败时回退到完整 authenticate。
-            }
-        }
-        const result = await this._auth.authenticate(gatewayUrl, aid);
-        const token = String(result.access_token ?? '');
-        if (!token)
-            throw new StateError('authenticate did not return access_token');
-        const fallbackIdentity = {
-            ...identity,
-            access_token: token,
-            refresh_token: String(result.refresh_token ?? identity.refresh_token ?? ''),
-        };
-        const fallbackExpiresAt = Number(result.expires_at ?? identity.expires_at ?? NaN);
-        if (Number.isFinite(fallbackExpiresAt))
-            fallbackIdentity.expires_at = fallbackExpiresAt;
-        this._identity = await this._auth.loadIdentityOrNone(aid) ?? fallbackIdentity;
-        return token;
-    }
-    async _uploadAgentMd(content) {
-        const target = String(this._aid ?? this._currentAid?.aid ?? '').trim();
-        if (!target)
-            throw new StateError('uploadAgentMd requires local AID');
-        const gatewayUrl = await this._resolveGatewayForAid(target);
-        this._gatewayUrl = gatewayUrl;
-        const token = await this._ensureAgentMdUploadToken(target, gatewayUrl);
-        const response = await fetchWithTimeout(await this._resolveAgentMdUrl(target), {
-            method: 'PUT',
-            headers: {
-                Authorization: `Bearer ${token}`,
-                'Content-Type': 'text/markdown; charset=utf-8',
-            },
-            body: content,
-        });
-        if (response.status === 404) {
-            throw new NotFoundError(`agent.md endpoint not found for aid: ${target}`);
-        }
-        if (!response.ok) {
-            const message = (await response.text()).trim();
-            throw new AUNError(`upload agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`);
-        }
-        const payload = await response.json();
-        if (!isJsonObject(payload))
-            throw new AUNError('upload agent.md returned invalid JSON payload');
-        return payload;
-    }
-    async _downloadAgentMd(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('downloadAgentMd requires non-empty aid');
-        const cached = this._agentMdCache.get(target);
-        const url = await this._resolveAgentMdUrl(target);
-        const response = await fetchWithTimeout(url, {
-            method: 'GET',
-            headers: { Accept: 'text/markdown' },
-            redirect: 'follow',
-        });
-        if (response.status === 304 && typeof cached?.text === 'string') {
-            return String(cached.text);
-        }
-        if (response.status === 404) {
-            throw new NotFoundError(`agent.md not found for aid: ${target}`);
-        }
-        if (!response.ok) {
-            const message = (await response.text()).trim();
-            throw new AUNError(`download agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`);
-        }
-        const text = await response.text();
-        const etag = String(response.headers?.get('ETag') ?? response.headers?.get('etag') ?? '').trim();
-        const lastModified = String(response.headers?.get('Last-Modified') ?? response.headers?.get('last-modified') ?? '').trim();
-        this._agentMdCache.set(target, {
-            ...(cached ?? {}),
-            text,
-            etag,
-            lastModified,
-            remote_etag: etag,
-            last_modified: lastModified,
-        });
-        return text;
-    }
-    async _headAgentMd(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('headAgentMd requires non-empty aid');
-        const response = await fetchWithTimeout(await this._resolveAgentMdUrl(target), {
-            method: 'HEAD',
-            headers: { Accept: 'text/markdown' },
-        });
-        const etag = String(response.headers?.get('ETag') ?? response.headers?.get('etag') ?? '').trim();
-        const lastModified = String(response.headers?.get('Last-Modified') ?? response.headers?.get('last-modified') ?? '').trim();
-        if (response.status === 404) {
-            return { aid: target, found: false, etag: '', last_modified: '', status: 404 };
-        }
-        if (!response.ok) {
-            throw new AUNError(`head agent.md failed: HTTP ${response.status}`);
-        }
-        const cached = this._agentMdCache.get(target) ?? {};
-        this._agentMdCache.set(target, {
-            ...cached,
-            etag,
-            lastModified,
-            remote_etag: etag,
-            last_modified: lastModified,
-        });
-        return { aid: target, found: true, etag, last_modified: lastModified, status: response.status };
-    }
-    async _verifyAgentMd(content, aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('verifyAgentMd requires non-empty aid');
-        let peer = target === this._currentAid?.aid ? this._currentAid : null;
-        if (!peer) {
-            let certPem = String(await this._tokenStore.loadCert(target) ?? '').trim();
-            if (!certPem) {
-                certPem = String(await this._fetchPeerCert(target) ?? '').trim();
-            }
-            if (!certPem)
-                throw new NotFoundError(`certificate not found for aid: ${target}`);
-            peer = await AID.create({
-                aid: target,
-                aunPath: this.configModel.aunPath,
-                certPem,
-                privateKeyPem: null,
-                certValid: true,
-                privateKeyValid: false,
-            });
-        }
-        const result = await peer.verifyAgentMd(content);
-        if (!result.ok)
-            throw new AUNError(result.error.message);
-        return { ...result.data, verified: result.data.status === 'verified' };
-    }
-    /**
-     * 浏览器版本 publishAgentMd。默认从 {agentMdPath}/{self_aid}/agent.md 的等价 IndexedDB 正文读取，
-     * 然后签名、上传，并刷新 agentmd.json 元数据。
-     *
-     * 兼容旧浏览器调用：传入 content 时会先写入等价正文，再从该正文发布。
-     */
-    async publishAgentMd(content) {
-        const target = this._agentMdOwnerAid();
-        if (!target || !this._currentAid) {
-            throw new ValidationError('publishAgentMd requires local AID');
-        }
-        if (content !== undefined && content !== null) {
-            const text = String(content ?? '');
-            if (text.length === 0) {
-                throw new ValidationError('publishAgentMd requires non-empty content');
-            }
-            await this._saveAgentMdRecord(target, {
-                content: text,
-                local_etag: await this._agentMdContentEtag(text),
-                fetched_at: Date.now(),
-            });
-        }
-        const localContent = await this._readAgentMdContent(target);
-        if (localContent === null || localContent.length === 0) {
-            throw new ValidationError('publishAgentMd requires local agent.md content');
-        }
-        const signedResult = await this._currentAid?.signAgentMd(localContent);
-        if (!signedResult?.ok) {
-            throw new StateError(signedResult?.error.message ?? 'publishAgentMd requires a valid local AID private key');
-        }
-        const signed = signedResult.data.signed;
-        const result = await this._uploadAgentMd(signed);
-        this._localAgentMdEtag = await this._agentMdContentEtag(signed);
-        const remoteEtag = isJsonObject(result) ? String(result.etag ?? '').trim() : '';
-        if (remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        await this._saveAgentMdRecord(target, {
-            content: signed,
-            local_etag: this._localAgentMdEtag,
-            remote_etag: remoteEtag || undefined,
-            last_modified: isJsonObject(result) ? String(result.last_modified ?? '').trim() : '',
-            fetched_at: Date.now(),
-            remote_status: remoteEtag ? 'found' : 'unknown',
-            last_error: '',
-        });
-        return result;
-    }
-    /**
-     * 浏览器版本 fetchAgentMd。aid 缺省时取自身；下载后的正文固定写入
-     * {agentMdPath}/{aid}/agent.md 的等价 IndexedDB 正文，agentmd.json 只保存元数据。
-     */
-    async _fetchAgentMdCache(aid) {
-        const target = String(aid ?? this._aid ?? '').trim();
-        if (!target) {
-            throw new ValidationError('fetchAgentMd requires aid (or local AID)');
-        }
-        const content = await this._downloadAgentMd(target);
-        const signature = await this._verifyAgentMd(content, target);
-        const isSelf = target === (this._aid ?? '');
-        const localEtag = await this._agentMdContentEtag(content);
-        const cacheMeta = this._agentMdAuthCacheMeta(target);
-        const remoteEtag = String(cacheMeta.etag ?? '').trim();
-        const lastModified = String(cacheMeta.lastModified ?? cacheMeta.last_modified ?? '').trim();
-        if (isSelf) {
-            this._localAgentMdEtag = localEtag;
-            if (remoteEtag)
-                this._remoteAgentMdEtag = remoteEtag;
-        }
-        await this._saveAgentMdRecord(target, {
-            content,
-            local_etag: localEtag,
-            remote_etag: remoteEtag || undefined,
-            last_modified: lastModified || undefined,
-            fetched_at: Date.now(),
-            remote_status: 'found',
-            verify_status: isJsonObject(signature) ? String(signature.status ?? '') : '',
-            verify_error: isJsonObject(signature) ? String(signature.reason ?? '') : '',
-            last_error: '',
-        });
-        let in_sync = null;
-        if (isSelf) {
-            const remote = remoteEtag || this._remoteAgentMdEtag || '';
-            in_sync = localEtag && remote ? localEtag === remote : false;
-        }
-        return {
-            aid: target,
-            content,
-            signature: signature,
-            in_sync,
-        };
-    }
-    getLocalAgentMdEtag() {
-        return this._localAgentMdEtag;
-    }
-    getRemoteAgentMdEtag() {
-        return this._remoteAgentMdEtag;
-    }
-    async _agentMdContentEtag(content) {
-        const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(String(content ?? '')));
-        const hex = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, '0')).join('');
-        return `"${hex}"`;
-    }
-    _agentMdOwnerAid() {
-        return String(this._aid ?? '').trim();
-    }
-    _agentMdDefaultRoot() {
-        return this._joinAgentMdPath(this.configModel.aunPath || '.', 'AIDs');
-    }
-    _joinAgentMdPath(base, name) {
-        const left = String(base ?? '').trim().replace(/[\\/]+$/g, '');
-        return left ? `${left}/${name}` : name;
-    }
-    _agentMdRoot() {
-        return this._agentMdPath || this._agentMdDefaultRoot();
-    }
-    _agentMdSafeAid(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target || target.includes('/') || target.includes('\\') || target.includes('\0')) {
-            throw new ValidationError('agent.md aid is empty or contains path separators');
-        }
-        return target;
-    }
-    _agentMdMetaKey(aid) {
-        return `${this._agentMdSafeAid(aid)}/agentmd.json`;
-    }
-    _agentMdContentKey(aid) {
-        return `${this._agentMdSafeAid(aid)}/agent.md`;
-    }
-    async _readAgentMdStorage(logicalKey) {
-        const key = String(logicalKey ?? '').trim();
-        if (!key)
-            return null;
-        const load = this._tokenStore.loadAgentMdCache;
-        if (typeof load !== 'function') {
-            throw new Error('IndexedDB agent.md storage unavailable');
-        }
-        const record = await load.call(this._tokenStore, this._agentMdRoot(), key);
-        if (record && Object.prototype.hasOwnProperty.call(record, 'content')) {
-            return String(record.content ?? '');
-        }
-        return null;
-    }
-    async _writeAgentMdStorage(logicalKey, content) {
-        const key = String(logicalKey ?? '').trim();
-        if (!key)
-            return;
-        const save = this._tokenStore.upsertAgentMdCache;
-        if (typeof save !== 'function') {
-            throw new Error('IndexedDB agent.md storage unavailable');
-        }
-        const text = String(content ?? '');
-        await save.call(this._tokenStore, this._agentMdRoot(), key, {
-            content: text,
-            local_etag: await this._agentMdContentEtag(text),
-            fetched_at: Date.now(),
-        });
-    }
-    async _withAgentMdLock(fn) {
-        const previous = this._agentMdLock.catch(() => undefined);
-        let release;
-        const current = new Promise((resolve) => { release = resolve; });
-        this._agentMdLock = previous.then(() => current);
-        await previous;
-        try {
-            return await fn();
-        }
-        finally {
-            release();
-        }
-    }
-    _normalizeAgentMdRecord(aid, data) {
-        if (!isJsonObject(data))
-            return {};
-        const record = {};
-        for (const [key, value] of Object.entries(data)) {
-            if (key !== 'content')
-                record[key] = value;
-        }
-        record.aid = this._agentMdSafeAid(String(record.aid ?? aid));
-        for (const key of ['fetched_at', 'observed_at', 'checked_at', 'updated_at']) {
-            record[key] = Number(record[key] ?? 0) || 0;
-        }
-        return record;
-    }
-    async _writeAgentMdRecordUnlocked(aid, record) {
-        const payload = {};
-        for (const [key, value] of Object.entries(record)) {
-            if (key !== 'content' && value !== undefined && value !== null)
-                payload[key] = value;
-        }
-        payload.aid = this._agentMdSafeAid(aid);
-        await this._writeAgentMdStorage(this._agentMdMetaKey(aid), `${JSON.stringify(payload, null, 2)}\n`);
-    }
-    async _readAgentMdRecordUnlocked(aid) {
-        const raw = await this._readAgentMdStorage(this._agentMdMetaKey(aid));
-        if (raw === null)
-            return {};
-        try {
-            return this._normalizeAgentMdRecord(aid, JSON.parse(raw));
-        }
-        catch (err) {
-            this._clientLog.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            return {};
-        }
-    }
-    async _readAgentMdContent(aid) {
-        return await this._readAgentMdStorage(this._agentMdContentKey(aid));
-    }
-    async _writeAgentMdContent(aid, content) {
-        await this._writeAgentMdStorage(this._agentMdContentKey(aid), String(content ?? ''));
-    }
-    _agentMdAuthCacheMeta(aid) {
-        try {
-            const record = this._agentMdCache.get(String(aid ?? '').trim());
-            return record && typeof record === 'object' ? { ...record } : {};
-        }
-        catch {
-            return {};
-        }
-    }
-    async _loadAgentMdRecord(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            return null;
-        try {
-            const loaded = await this._withAgentMdLock(async () => {
-                const record = await this._readAgentMdRecordUnlocked(target);
-                const next = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
-                try {
-                    const content = await this._readAgentMdContent(target);
-                    if (content !== null) {
-                        next.content = content;
-                        next.local_etag = await this._agentMdContentEtag(content);
-                    }
-                    else {
-                        // 元数据存在但正文缺失
-                        const metaRaw = await this._readAgentMdStorage(this._agentMdMetaKey(target));
-                        if (metaRaw !== null) {
-                            this._clientLog.warn(`agent.md content read failed: aid=${target}`);
-                        }
-                    }
-                }
-                catch (err) {
-                    this._clientLog.warn(`agent.md content read failed: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
-                }
-                return next;
-            });
-            if (Object.keys(loaded).length <= 1)
-                return null;
-            this._agentMdCache.set(target, { ...loaded });
-            return { ...loaded };
-        }
-        catch (err) {
-            this._clientLog.debug(`agent.md cache load skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
-        }
-        return null;
-    }
-    async _saveAgentMdRecord(aid, fields) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            return {};
-        try {
-            const inputFields = { ...fields };
-            const hasContent = Object.prototype.hasOwnProperty.call(inputFields, 'content') && inputFields.content !== undefined && inputFields.content !== null;
-            if (hasContent) {
-                const text = String(inputFields.content ?? '');
-                await this._writeAgentMdContent(target, text);
-                if (!inputFields.local_etag)
-                    inputFields.local_etag = await this._agentMdContentEtag(text);
-                if (!inputFields.fetched_at)
-                    inputFields.fetched_at = Date.now();
-            }
-            delete inputFields.content;
-            const record = await this._withAgentMdLock(async () => {
-                const next = { ...(await this._readAgentMdRecordUnlocked(target)), aid: target };
-                for (const [key, value] of Object.entries(inputFields)) {
-                    if (value !== undefined && value !== null)
-                        next[key] = value;
-                }
-                next.updated_at = Date.now();
-                await this._writeAgentMdRecordUnlocked(target, next);
-                return next;
-            });
-            const loaded = { ...record };
-            if (hasContent)
-                loaded.content = String(fields.content ?? '');
-            this._agentMdCache.set(target, { ...loaded });
-            const owner = this._agentMdOwnerAid();
-            if (target === owner) {
-                const localEtag = String(loaded.local_etag ?? '').trim();
-                const remoteEtag = String(loaded.remote_etag ?? '').trim();
-                if (localEtag)
-                    this._localAgentMdEtag = localEtag;
-                if (remoteEtag)
-                    this._remoteAgentMdEtag = remoteEtag;
-            }
-            return { ...loaded };
-        }
-        catch (err) {
-            this._clientLog.debug(`agent.md cache save skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
-        }
-        return {};
-    }
-    async _agentMdHasLocalContent(aid, record) {
-        if (record && typeof record.content === 'string' && record.content.length > 0)
-            return true;
-        try {
-            return (await this._readAgentMdContent(aid)) !== null;
-        }
-        catch {
-            return false;
-        }
-    }
-    _agentMdCheckedAtFresh(checkedAtMs, maxUnsyncedDays) {
-        const days = Number(maxUnsyncedDays || 0);
-        if (!Number.isFinite(days) || days <= 0)
-            return false;
-        if (!Number.isFinite(checkedAtMs) || checkedAtMs <= 0)
-            return false;
-        return Date.now() - checkedAtMs <= days * 86400000;
-    }
-    _agentMdLastModifiedFresh(lastModified, maxUnsyncedDays) {
-        const days = Number(maxUnsyncedDays || 0);
-        if (!Number.isFinite(days) || days <= 0)
-            return false;
-        const ts = Date.parse(String(lastModified ?? '').trim());
-        if (!Number.isFinite(ts))
-            return false;
-        return Date.now() <= ts + days * 86400000;
-    }
-    async _scheduleAgentMdFetchIfMissing(aid, record, source = '') {
-        const target = String(aid ?? '').trim();
-        if (!target || await this._agentMdHasLocalContent(target, record))
-            return;
-        if (this._agentMdFetchInflight.has(target))
-            return;
-        this._agentMdFetchInflight.add(target);
-        try {
-            await this._fetchAgentMdCache(target);
-        }
-        catch (err) {
-            await this._saveAgentMdRecord(target, {
-                last_error: err instanceof Error ? err.message : String(err),
-                remote_status: 'found',
-            });
-            this._clientLog.debug(`agent.md auto fetch failed: aid=${target} source=${source || '-'} err=${err instanceof Error ? err.message : String(err)}`);
-        }
-        finally {
-            this._agentMdFetchInflight.delete(target);
-        }
-    }
-    async _observeAgentMdMeta(aid, etag = '', lastModified = '', source = '') {
-        const target = String(aid ?? '').trim();
-        const remoteEtag = String(etag ?? '').trim();
-        const remoteLastModified = String(lastModified ?? '').trim();
-        if (!target || (!remoteEtag && !remoteLastModified))
-            return;
-        let before = this._agentMdCache.get(target);
-        if (!before || typeof before !== 'object')
-            before = await this._loadAgentMdRecord(target) ?? {};
-        const same = (!remoteEtag || String(before.remote_etag ?? '').trim() === remoteEtag) &&
-            (!remoteLastModified || String(before.last_modified ?? '').trim() === remoteLastModified);
-        let record = { ...before };
-        if (!same || Object.keys(before).length === 0) {
-            const fields = {
-                observed_at: Date.now(),
-                remote_status: 'found',
-            };
-            if (remoteEtag)
-                fields.remote_etag = remoteEtag;
-            if (remoteLastModified)
-                fields.last_modified = remoteLastModified;
-            record = await this._saveAgentMdRecord(target, fields) || record;
-        }
-        if (target === this._agentMdOwnerAid() && remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        await this._scheduleAgentMdFetchIfMissing(target, record, source);
-        this._clientLog.debug(`agent.md meta observed: aid=${target} etag=${remoteEtag || '-'} last_modified=${remoteLastModified || '-'} source=${source || '-'}`);
-    }
-    async _observeAgentMdEtag(aid, etag, source = '') {
-        await this._observeAgentMdMeta(aid, etag, '', source);
+    async uploadAgentMd(content) {
+        return await this._agentMdManager.upload(content);
     }
     async _observeAgentMdFromEnvelope(envelope) {
-        if (!isJsonObject(envelope))
-            return;
-        const env = envelope;
-        if (!isJsonObject(env.agent_md))
-            return;
-        const agentMd = env.agent_md;
-        if (!isJsonObject(agentMd.sender))
-            return;
-        const sender = agentMd.sender;
-        let senderAid = String(sender.aid ?? '').trim();
-        if (!senderAid) {
-            const aad = isJsonObject(env.aad) ? env.aad : {};
-            senderAid = String(aad.from ?? env.from ?? '').trim();
-        }
-        await this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
-    }
-    async _checkAgentMdCache(aid, maxUnsyncedDays = 0) {
-        const target = String(aid ?? this._aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('checkAgentMd requires aid (or local AID)');
-        const before = await this._loadAgentMdRecord(target) ?? {};
-        const localEtag = String(before.local_etag ?? '').trim();
-        const localFound = !!(Object.keys(before).length > 0 && (String(before.content ?? '') || localEtag));
-        const remoteEtagCached = String(before.remote_etag ?? '').trim();
-        const lastModifiedCached = String(before.last_modified ?? '').trim();
-        const checkedAtCached = Number(before.checked_at ?? 0);
-        const cachedInSync = !!(localFound && localEtag && remoteEtagCached && localEtag === remoteEtagCached);
-        // max_unsynced_days > 0 且距上次 HEAD 在窗口内 → 直接返回缓存；否则强制 HEAD。
-        if (cachedInSync && this._agentMdCheckedAtFresh(checkedAtCached, maxUnsyncedDays)) {
-            return {
-                aid: target,
-                local_found: true,
-                remote_found: true,
-                local_etag: localEtag,
-                remote_etag: remoteEtagCached,
-                in_sync: true,
-                last_modified: lastModifiedCached,
-                status: 200,
-                cached: true,
-                verify_status: String(before.verify_status ?? ''),
-                verify_error: String(before.verify_error ?? ''),
-            };
-        }
-        const now = Date.now();
-        let remote;
-        try {
-            remote = await this._headAgentMd(target);
-        }
-        catch (err) {
-            await this._saveAgentMdRecord(target, { checked_at: now, remote_status: 'error', last_error: err instanceof Error ? err.message : String(err) });
-            throw err;
-        }
-        const remoteFound = !!remote.found;
-        const remoteEtag = String(remote.etag ?? '').trim();
-        const lastModified = String(remote.last_modified ?? remote.lastModified ?? '').trim();
-        const saved = await this._saveAgentMdRecord(target, {
-            remote_etag: remoteFound ? remoteEtag : '',
-            last_modified: lastModified,
-            checked_at: now,
-            remote_status: remoteFound ? 'found' : 'missing',
-            last_error: '',
-        });
-        if (target === this._agentMdOwnerAid() && remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        const inSync = !!(localFound && remoteFound && localEtag && remoteEtag && localEtag === remoteEtag);
-        return {
-            aid: target,
-            local_found: localFound,
-            remote_found: remoteFound,
-            local_etag: localEtag,
-            remote_etag: remoteEtag,
-            in_sync: inSync,
-            last_modified: lastModified,
-            status: Number(remote.status ?? (remoteFound ? 200 : 404)),
-            cached: false,
-            verify_status: String(saved.verify_status ?? before.verify_status ?? ''),
-            verify_error: String(saved.verify_error ?? before.verify_error ?? ''),
-        };
+        await this._agentMdManager.observeEnvelope(envelope);
     }
     /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
     async _observeRpcMeta(meta) {
-        if (!isJsonObject(meta))
-            return;
-        const etag = String(meta.agent_md_etag ?? '').trim();
-        if (etag) {
-            this._remoteAgentMdEtag = etag;
-            await this._observeAgentMdMeta(this._aid ?? '', etag, '', 'rpc.self');
-        }
-        const etags = meta.agent_md_etags;
-        if (isJsonObject(etags)) {
-            // role key 优先级：requester / peer 是新规范，其余是兼容旧 SDK 的别名。
-            for (const key of ['requester', 'peer', 'receiver', 'target', 'to', 'sender', 'from']) {
-                const item = etags[key];
-                if (!isJsonObject(item))
-                    continue;
-                await this._observeAgentMdMeta(String(item.aid ?? ''), String(item.etag ?? ''), String(item.last_modified ?? item.lastModified ?? ''), `rpc.${key}`);
-            }
-        }
+        await this._agentMdManager.observeRpcMeta(meta, this._aid);
     }
     get state() {
         return this._publicState(this._state);
@@ -1598,9 +1015,6 @@ export class AUNClient {
         this.config.aun_path = nextConfig.aunPath;
         this.config.root_ca_path = nextConfig.rootCaPem;
         this.config.seed_password = nextConfig.seedPassword;
-        this._agentMdPath = this._agentMdDefaultRoot();
-        this._agentMdCache.clear();
-        this._agentMdFetchInflight.clear();
         this._peerCache.clear();
         this._certCache.clear();
         this._gatewayUrl = null;
@@ -1615,7 +1029,7 @@ export class AUNClient {
         this._logDiscovery = this._logger.for('aun_core.discovery');
         this._logEvents = this._logger.for('aun_core.events');
         this._discovery = new GatewayDiscovery();
-        this._tokenStore = new IndexedDBKeyStore({});
+        this._tokenStore = new IndexedDBTokenStore();
         this._auth = new AuthFlow({
             tokenStore: this._tokenStore,
             crypto: new CryptoProvider(),
@@ -1625,6 +1039,24 @@ export class AUNClient {
             rootCaPem: nextConfig.rootCaPem,
             verifySsl: nextConfig.verifySsl,
         });
+        this._agentMdManager = createAgentMdManagerForRuntime({
+            config: () => this.configModel,
+            logger: () => this._logger.for('aun_core.agent_md'),
+            ownerAid: () => this._aid,
+            currentAid: () => this._currentAid,
+            gateway: {
+                resolve: (target) => this._resolveGatewayForAid(target),
+                get: () => this._gatewayUrl,
+                set: (gatewayUrl) => { this._gatewayUrl = gatewayUrl; },
+            },
+            identity: {
+                get: () => this._identity,
+                set: (identity) => { this._identity = identity; },
+            },
+            auth: () => this._auth,
+            tokenStore: () => this._tokenStore,
+            fetchPeerCert: (target) => this._fetchPeerCert(target),
+        });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: DEFAULT_SESSION_OPTIONS.timeouts.call,
@@ -2759,8 +2191,9 @@ export class AUNClient {
         // 注入本地/远端 agent.md etag，让应用层判断版本一致性；失败不影响业务。
         if (isJsonObject(payload)) {
             try {
-                const localEtag = this._localAgentMdEtag || '';
-                const remoteEtag = this._remoteAgentMdEtag || '';
+                const snapshot = this._agentMdManager.eventSnapshot();
+                const localEtag = snapshot?.local_etag || '';
+                const remoteEtag = snapshot?.remote_etag || '';
                 if ((localEtag || remoteEtag) && payload._agent_md === undefined) {
                     payload._agent_md = {
                         local_etag: localEtag,
@@ -4208,8 +3641,8 @@ export class AUNClient {
         if ('device_id' in params && String(params.device_id ?? '').trim() !== this._deviceId) {
             throw new ValidationError('message.pull/message.ack device_id must match the current client instance');
         }
-        const slotId = normalizeInstanceId(params.slot_id ?? this._slotId, 'slot_id', { allowEmpty: true });
-        if (slotId !== this._slotId) {
+        const slotId = normalizeSlotId(params.slot_id ?? this._slotId, this._slotId);
+        if (slotIsolationKey(slotId) !== slotIsolationKey(this._slotId)) {
             throw new ValidationError('message.pull/message.ack slot_id must match the current client instance');
         }
         params.device_id = this._deviceId;
@@ -4719,7 +4152,7 @@ export class AUNClient {
     async _initV2Session() {
         if (!this._aid)
             return;
-        // 私钥由 AIDStore 管理，直接从 _currentAid 读取明文私钥
+        // 私钥来自当前 AID 值对象，AUNClient 不从持久化存储读取私钥。
         const currentAid = this._currentAid;
         if (!currentAid?.privateKeyPem) {
             this._clientLog.warn('V2 session init skipped: no AID private key');