@agentunion/fastaun-browser 0.3.5 → 0.4.0

package/dist/client.js

@@ -11,9 +11,6 @@ import { GatewayDiscovery } from './discovery.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
-import { AuthNamespace } from './namespaces/auth.js';
-import { CustodyNamespace } from './namespaces/custody.js';
-import { MetaNamespace } from './namespaces/meta.js';
 import { CryptoProvider, uint8ToBase64, base64ToUint8, pemToArrayBuffer, p1363ToDer, certificateSha256Fingerprint, ecdsaSignDer, ecdsaVerifyDer, importCertPublicKeyEcdsa, importPrivateKeyEcdsa, } from './crypto.js';
 import { IndexedDBKeyStore } from './keystore/indexeddb.js';
 import { V2Session, V2KeyStore } from './v2/session/index.js';
@@ -21,8 +18,9 @@ import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { computeStateCommitment } from './v2/state/index.js';
 import { AUNLogger } from './logger.js';
-import { AUNError, AuthError, ConnectionError, E2EEError, PermissionError, StateError, ValidationError, } from './errors.js';
-import { isJsonObject, } from './types.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';
 /**
  * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
  * 等价于 Python json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
@@ -171,6 +169,12 @@ const DEFAULT_SESSION_OPTIONS = {
         http: 30.0,
     },
 };
+const PROTECTED_HEADERS_METHODS = new Set([
+    'message.send',
+    'group.send',
+    'message.thought.put',
+    'group.thought.put',
+]);
 const RECONNECT_MIN_BASE_DELAY_SECONDS = 1.0;
 const RECONNECT_MAX_BASE_DELAY_SECONDS = 64.0;
 const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
@@ -213,6 +217,7 @@ 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
  */
@@ -245,6 +250,34 @@ 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, discoveryPort) {
+    const host = String(aid ?? '').trim();
+    if (!host)
+        return '';
+    if (discoveryPort && !host.includes(':'))
+        return `${host}:${discoveryPort}`;
+    return host;
+}
+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);
+    }
+}
 /**
  * 跨域时将 Gateway URL 替换为 peer 所在域的 Gateway URL。
  *
@@ -453,6 +486,85 @@ function extractV2EnvelopeFromSource(source) {
     }
     return null;
 }
+function truthyBool(value) {
+    if (value === true || value === 1)
+        return true;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
+    }
+    return false;
+}
+function isEncryptedEnvelopePayload(payload) {
+    if (!isJsonObject(payload))
+        return false;
+    const payloadType = String(payload.type ?? '').trim();
+    if (payloadType.startsWith('e2ee.'))
+        return true;
+    if (!String(payload.ciphertext ?? '').trim())
+        return false;
+    return payload.nonce !== undefined
+        || payload.tag !== undefined
+        || payload.recipient !== undefined
+        || payload.recipients !== undefined
+        || payload.wrapped_key !== undefined
+        || payload.recipients_digest !== undefined;
+}
+function encryptedPushEnvelope(msg) {
+    if (isEncryptedEnvelopePayload(msg.payload))
+        return msg.payload;
+    if (typeof msg.envelope_json === 'string' && msg.envelope_json.trim()) {
+        try {
+            const parsed = JSON.parse(msg.envelope_json);
+            if (isEncryptedEnvelopePayload(parsed))
+                return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function isEncryptedPushMessage(msg) {
+    if (truthyBool(msg.encrypted))
+        return true;
+    return encryptedPushEnvelope(msg) !== null;
+}
+function isV2EncryptedEnvelopePayload(envelope) {
+    if (!envelope)
+        return false;
+    const payloadType = String(envelope.type ?? '').trim();
+    if (payloadType === 'e2ee.p2p_encrypted' || payloadType === 'e2ee.group_encrypted')
+        return true;
+    return String(envelope.version ?? '').trim().toLowerCase() === 'v2' && payloadType.startsWith('e2ee.');
+}
+function safeUndecryptablePushEvent(msg, group) {
+    const event = {
+        message_id: msg.message_id ?? null,
+        from: msg.from ?? null,
+        seq: msg.seq ?? null,
+        timestamp: msg.timestamp ?? msg.t_server ?? null,
+        device_id: msg.device_id ?? null,
+        slot_id: msg.slot_id ?? null,
+        _decrypt_error: 'encrypted push payload is not decryptable on raw push path',
+        _decrypt_stage: 'push_envelope',
+    };
+    if (group) {
+        event.group_id = msg.group_id ?? null;
+    }
+    else {
+        event.to = msg.to ?? null;
+    }
+    const envelope = encryptedPushEnvelope(msg);
+    if (envelope) {
+        event._envelope_type = String(envelope.type ?? '');
+        event._suite = String(envelope.suite ?? '');
+        if (isV2EncryptedEnvelopePayload(envelope)) {
+            attachV2EnvelopeMetadata(event, v2E2eeMeta(envelope));
+        }
+    }
+    return event;
+}
 function metadataWithoutAuth(value) {
     if (!isJsonObject(value))
         return null;
@@ -502,6 +614,22 @@ function normalizeDeliveryModeConfig(raw, opts = {}) {
         affinity_ttl_ms: affinityTtlMs,
     };
 }
+function assertClientOptions(value, label) {
+    if (value == null)
+        return;
+    if (typeof value !== 'object' || Array.isArray(value) || value instanceof AID) {
+        throw new ValidationError(`${label} must be an options object`);
+    }
+}
+function clientOptionsConfig(options) {
+    const raw = { ...(options ?? {}) };
+    if (Object.prototype.hasOwnProperty.call(raw, 'aid')) {
+        throw new ValidationError('AUNClient options must not include aid; pass an AID object as the first argument');
+    }
+    delete raw.debug;
+    delete raw.protected_headers;
+    return raw;
+}
 /**
  * AUN Core SDK 客户端 — 浏览器版本。
  *
@@ -522,6 +650,8 @@ export class AUNClient {
     _aid = null;
     _identity = null;
     _state = 'idle';
+    _currentAid = null;
+    _instanceProtectedHeaders = null;
     _gatewayUrl = null;
     _deviceId;
     _slotId;
@@ -536,12 +666,6 @@ export class AUNClient {
     _keystore;
     _auth;
     _transport;
-    /** 认证命名空间 */
-    auth;
-    /** AID 托管命名空间 */
-    custody;
-    /** 元数据命名空间（心跳、状态、信任根管理） */
-    meta;
     // E2EE 编排状态（内存缓存）
     _certCache = new Map();
     // 后台任务 handle（浏览器 setInterval/setTimeout）
@@ -582,7 +706,7 @@ export class AUNClient {
     _localAgentMdEtag = '';
     /** gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。 */
     _remoteAgentMdEtag = '';
-    /** 浏览器侧 AgentMDs 逻辑根目录，正文映射到 IndexedDB 里的 {aid}/agent.md。 */
+    /** 浏览器侧 AIDs 逻辑根目录，正文映射到 IndexedDB 里的 {aid}/agent.md。 */
     _agentMdPath = '';
     _agentMdCache = new Map();
     _agentMdFetchInflight = new Set();
@@ -607,6 +731,14 @@ export class AUNClient {
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
+    // 重连状态追踪（对齐 Python client.py）
+    _nextRetryAt = null;
+    _retryAttempt = 0;
+    _retryMaxAttempts = 0;
+    _lastError = null;
+    _lastErrorCode = null;
+    /** 对端 AID 缓存（aid string → AID 对象） */
+    _peerCache = new Map();
     /**
      * 缓存最近一次服务端 gateway.disconnect 信息（含 code/reason/detail），
      * 让后续 connection.state(terminal_failed) 也能携带 detail（如配额超限信息）。
@@ -620,17 +752,32 @@ export class AUNClient {
     _logKeystore;
     _logDiscovery;
     _logEvents;
-    constructor(config, _debug = false) {
-        const rawConfig = config ?? {};
+    constructor(first, second) {
+        if (typeof first === 'string') {
+            throw new ValidationError('AUNClient aid must be an AID object, not a string');
+        }
+        if (typeof second === 'boolean') {
+            throw new ValidationError('AUNClient debug must be passed as options.debug');
+        }
+        const inputAid = first instanceof AID ? first : null;
+        if (!inputAid && second !== undefined) {
+            throw new ValidationError('AUNClient options-only construction accepts a single options object');
+        }
+        const options = inputAid ? (second ?? {}) : (first ?? {});
+        assertClientOptions(options, 'AUNClient options');
+        const rawConfig = clientOptionsConfig(options);
+        if (inputAid)
+            rawConfig.aun_path = inputAid.aunPath;
+        const _debug = !!options?.debug;
         this.configModel = createConfig(rawConfig);
-        const initAid = String(rawConfig.aid ?? '').trim() || null;
+        const initAid = inputAid ? inputAid.aid : null;
         this.config = {
             aun_path: this.configModel.aunPath,
             root_ca_path: this.configModel.rootCaPem,
             seed_password: this.configModel.seedPassword,
         };
         this._agentMdPath = this._agentMdDefaultRoot();
-        this._deviceId = getDeviceId();
+        this._deviceId = (inputAid?.deviceId) || getDeviceId();
         // Logger 必须最早初始化（其他子模块构造时通过 logger 输出）
         this._logger = new AUNLogger({ debug: _debug, aunPath: this.configModel.aunPath });
         this._logger.bindDeviceId(this._deviceId);
@@ -644,7 +791,7 @@ export class AUNClient {
         this._dispatcher = new EventDispatcher();
         this._discovery = new GatewayDiscovery();
         this._keystore = new IndexedDBKeyStore({ encryptionSeed: this.configModel.seedPassword ?? undefined });
-        this._slotId = '';
+        this._slotId = inputAid?.slotId || 'default';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
         this._auth = new AuthFlow({
@@ -667,9 +814,21 @@ export class AUNClient {
                 this._clientLog.debug(`agent.md meta observer skipped: ${String(exc)}`);
             });
         });
-        this.auth = new AuthNamespace(this);
-        this.custody = new CustodyNamespace(this);
-        this.meta = new MetaNamespace(this);
+        if (inputAid) {
+            if (!inputAid.isPrivateKeyValid())
+                throw new StateError('AUNClient requires an AID with a valid private key');
+            this._currentAid = inputAid;
+            this._identity = {
+                aid: inputAid.aid,
+                private_key_pem: inputAid._privateKeyPem ?? '',
+                public_key_der_b64: inputAid.publicKey,
+                cert: inputAid.certPem,
+            };
+            this._state = 'disconnected';
+        }
+        if (options?.protected_headers !== undefined) {
+            this.setProtectedHeaders(options.protected_headers);
+        }
         // 注入 logger 到各子模块（构造时未传 logger，构造后通过 setLogger 注入）
         this._auth.setLogger(this._logAuth);
         this._transport.setLogger(this._logTransport);
@@ -677,18 +836,9 @@ export class AUNClient {
         if (typeof this._discovery.setLogger === 'function') {
             this._discovery.setLogger(this._logger.for('aun_core.discovery'));
         }
-        if (typeof this.auth.setLogger === 'function') {
-            this.auth.setLogger(this._logger.for('aun_core.namespace.auth'));
-        }
-        if (typeof this.custody.setLogger === 'function') {
-            this.custody.setLogger(this._logger.for('aun_core.namespace.custody'));
-        }
         if (typeof this._keystore.setLogger === 'function') {
             this._keystore.setLogger(this._logKeystore);
         }
-        if (typeof this.meta.setLogger === 'function') {
-            this.meta.setLogger(this._logger.for('aun_core.namespace.meta'));
-        }
         // 内部订阅：推送消息 re-publish 给用户（V2 加密消息走 _raw.peer.v2.message_received）
         this._dispatcher.subscribe('_raw.message.received', (data) => {
             this._onRawMessageReceived(data);
@@ -739,17 +889,182 @@ export class AUNClient {
     get aid() {
         return this._aid;
     }
-    setAgentMdPath(root) {
+    _setAgentMdRoot(root) {
         const next = String(root ?? '').trim() || this._agentMdDefaultRoot();
         this._agentMdPath = next;
         this._agentMdCache.clear();
         return next;
     }
-    setAgentMDPath(root) {
-        return this.setAgentMdPath(root);
+    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, this.configModel.discoveryPort);
+        return `${agentMdHttpScheme(gatewayUrl)}://${authority}/agent.md`;
     }
-    SetAgentMDPath(root) {
-        return this.setAgentMdPath(root);
+    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._keystore.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 正文读取，
@@ -777,8 +1092,12 @@ export class AUNClient {
         if (localContent === null || localContent.length === 0) {
             throw new ValidationError('publishAgentMd requires local agent.md content');
         }
-        const signed = await this.auth.signAgentMd(localContent);
-        const result = await this.auth.uploadAgentMd(signed);
+        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)
@@ -798,13 +1117,13 @@ export class AUNClient {
      * 浏览器版本 fetchAgentMd。aid 缺省时取自身；下载后的正文固定写入
      * {agentMdPath}/{aid}/agent.md 的等价 IndexedDB 正文，agentmd.json 只保存元数据。
      */
-    async fetchAgentMd(aid) {
+    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.auth.downloadAgentMd(target);
-        const signature = await this.auth.verifyAgentMd(content, { aid: target });
+        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);
@@ -853,7 +1172,7 @@ export class AUNClient {
         return String(this._aid ?? '').trim();
     }
     _agentMdDefaultRoot() {
-        return this._joinAgentMdPath(this.configModel.aunPath || '.', 'AgentMDs');
+        return this._joinAgentMdPath(this.configModel.aunPath || '.', 'AIDs');
     }
     _joinAgentMdPath(base, name) {
         const left = String(base ?? '').trim().replace(/[\\/]+$/g, '');
@@ -960,8 +1279,7 @@ export class AUNClient {
     }
     _agentMdAuthCacheMeta(aid) {
         try {
-            const store = this.auth._agentMdCache;
-            const record = store?.get(String(aid ?? '').trim());
+            const record = this._agentMdCache.get(String(aid ?? '').trim());
             return record && typeof record === 'object' ? { ...record } : {};
         }
         catch {
@@ -1086,7 +1404,7 @@ export class AUNClient {
             return;
         this._agentMdFetchInflight.add(target);
         try {
-            await this.fetchAgentMd(target);
+            await this._fetchAgentMdCache(target);
         }
         catch (err) {
             await this._saveAgentMdRecord(target, {
@@ -1147,7 +1465,7 @@ export class AUNClient {
         }
         await this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
     }
-    async checkAgentMd(aid, maxUnsyncedDays = 0) {
+    async _checkAgentMdCache(aid, maxUnsyncedDays = 0) {
         const target = String(aid ?? this._aid ?? '').trim();
         if (!target)
             throw new ValidationError('checkAgentMd requires aid (or local AID)');
@@ -1177,7 +1495,7 @@ export class AUNClient {
         const now = Date.now();
         let remote;
         try {
-            remote = await this.auth.headAgentMd(target);
+            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) });
@@ -1231,7 +1549,116 @@ export class AUNClient {
         }
     }
     get state() {
-        return this._state;
+        return this._publicState(this._state);
+    }
+    _publicState(state) {
+        return STATE_TO_PUBLIC[state] ?? state;
+    }
+    get currentAid() {
+        return this._currentAid;
+    }
+    get hasIdentity() {
+        return this._currentAid !== null && this.state !== ConnectionState.CLOSED;
+    }
+    get canSign() {
+        return this.hasIdentity && !!this._currentAid?.isPrivateKeyValid();
+    }
+    get canConnect() {
+        return this.hasIdentity && this.state !== ConnectionState.CLOSED;
+    }
+    get canSend() {
+        return this.state === ConnectionState.READY;
+    }
+    get isReady() { return this.canSend; }
+    get isOnline() {
+        return this.state === ConnectionState.READY
+            || this.state === ConnectionState.RECONNECTING
+            || this.state === ConnectionState.RETRY_BACKOFF;
+    }
+    get isClosed() { return this.state === ConnectionState.CLOSED; }
+    get aunPath() { return this.hasIdentity ? this._currentAid?.aunPath ?? this.configModel.aunPath : null; }
+    /** 下次重连时间（仅在 retry_backoff 状态时非 null，对齐 Python next_retry_at） */
+    get nextRetryAt() {
+        return this.state === ConnectionState.RETRY_BACKOFF ? this._nextRetryAt : null;
+    }
+    /** 距下次重连的剩余秒数（仅在 retry_backoff 状态时非 null，对齐 Python next_retry_in_seconds） */
+    get nextRetryInSeconds() {
+        const t = this.nextRetryAt;
+        if (t === null)
+            return null;
+        return Math.max(0, (t.getTime() - Date.now()) / 1000);
+    }
+    /** 当前重连尝试次数（对齐 Python retry_attempt） */
+    get retryAttempt() { return this._retryAttempt; }
+    /** 最大重连次数（0 = 无限，对齐 Python retry_max_attempts） */
+    get retryMaxAttempts() { return this._retryMaxAttempts; }
+    /** 最近一次错误（对齐 Python last_error） */
+    get lastError() { return this._lastError; }
+    /** 最近一次错误码（对齐 Python last_error_code） */
+    get lastErrorCode() { return this._lastErrorCode; }
+    loadIdentity(aid) {
+        if (!aid?.isPrivateKeyValid())
+            throw new StateError('loadIdentity requires an AID with a valid private key');
+        const publicState = this.state;
+        if (publicState !== ConnectionState.NO_IDENTITY && publicState !== ConnectionState.CLOSED) {
+            throw new StateError(`loadIdentity not allowed in state ${publicState}`);
+        }
+        this._currentAid = aid;
+        this._aid = aid.aid;
+        this._identity = {
+            aid: aid.aid,
+            private_key_pem: aid._privateKeyPem ?? '',
+            public_key_der_b64: aid.publicKey,
+            cert: aid.certPem,
+        };
+        this._auth._aid = aid.aid;
+        this._state = 'disconnected';
+        this._closing = false;
+    }
+    setProtectedHeaders(headers) {
+        if (!headers) {
+            this._instanceProtectedHeaders = null;
+            return;
+        }
+        const cleaned = {};
+        for (const [key, value] of Object.entries(headers)) {
+            if (key === '_auth')
+                continue;
+            cleaned[String(key)] = String(value);
+        }
+        this._instanceProtectedHeaders = Object.keys(cleaned).length ? cleaned : null;
+    }
+    getProtectedHeaders() {
+        return this._instanceProtectedHeaders ? { ...this._instanceProtectedHeaders } : null;
+    }
+    cachePeer(aid) {
+        if (!this.hasIdentity)
+            throw new StateError('cachePeer requires a loaded identity');
+        if (!aid.isCertValid())
+            throw new ValidationError('cachePeer requires an AID with a valid certificate');
+        this._peerCache.set(aid.aid, aid);
+        return aid;
+    }
+    getPeer(aid) {
+        if (!this.hasIdentity)
+            throw new StateError('getPeer requires a loaded identity');
+        return this._peerCache.get(String(aid ?? '').trim()) ?? null;
+    }
+    async lookupPeer(aid) {
+        if (!this.hasIdentity)
+            throw new StateError('lookupPeer requires a loaded identity');
+        const target = String(aid ?? '').trim();
+        if (!target)
+            throw new ValidationError('lookupPeer requires non-empty aid');
+        const cached = this._peerCache.get(target);
+        if (cached)
+            return cached;
+        throw new NotFoundError(`peer not found in cache: ${target}`);
+    }
+    peers() {
+        if (!this.hasIdentity)
+            throw new StateError('peers requires a loaded identity');
+        return [...this._peerCache.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, v]) => v);
     }
     get gatewayUrl() {
         return this._gatewayUrl;
@@ -1246,36 +1673,65 @@ export class AUNClient {
     get gatewayHealth() {
         return this._discovery.lastHealthy;
     }
-    /** 主动检查 gateway 可用性（GET /health） */
-    async checkGatewayHealth(gatewayUrl, timeout = 5000) {
+    // ── 生命周期 ──────────────────────────────────────
+    /** 仅认证当前身份，获取/刷新 token，但不建立长连接。 */
+    async authenticate(options = {}) {
         const tStart = Date.now();
-        this._clientLog.debug(`checkGatewayHealth enter: gateway=${gatewayUrl} timeout=${timeout}`);
+        const target = this._currentAid?.aid ?? this._aid ?? '';
+        if (!target || !this._currentAid?.isPrivateKeyValid()) {
+            throw new StateError('authenticate requires a loaded AID with a valid private key');
+        }
+        const publicState = this.state;
+        if (publicState !== ConnectionState.STANDBY && publicState !== ConnectionState.AUTHENTICATED) {
+            throw new StateError(`authenticate not allowed in state ${publicState}`);
+        }
+        if ('aid' in options || 'access_token' in options || 'token' in options || 'kite_token' in options) {
+            throw new ValidationError('authenticate options must not include aid or token fields; load an AID object first');
+        }
+        this._state = 'connecting';
         try {
-            const result = await this._discovery.checkHealth(gatewayUrl, timeout);
-            this._clientLog.debug(`checkGatewayHealth exit: elapsed=${Date.now() - tStart}ms healthy=${result}`);
+            const gateway = String(options.gateway ?? this._gatewayUrl ?? await this._resolveGatewayForAid(target)).trim();
+            const result = await this._auth.authenticate(gateway, target);
+            this._gatewayUrl = String(result.gateway ?? gateway);
+            this._identity = await this._auth.loadIdentityOrNone(target);
+            this._state = 'authenticated';
+            this._clientLog.debug(`authenticate exit: elapsed=${Date.now() - tStart}ms aid=${target}`);
             return result;
         }
         catch (err) {
-            this._clientLog.debug(`checkGatewayHealth exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            this._state = 'disconnected';
+            this._clientLog.debug(`authenticate exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
     }
-    // ── 生命周期 ──────────────────────────────────────
-    /**
-     * 连接到 Gateway。
-     *
-     * @param auth - 认证参数，必须包含 access_token 和 gateway
-     * @param options - 可选的会话选项（auto_reconnect, heartbeat_interval 等）
-     */
-    async connect(auth, options) {
+    /** 连接到 Gateway；身份来自构造函数或 loadIdentity(aid)，认证由 SDK 内部自动完成。 */
+    async connect(options = {}) {
         const tStart = Date.now();
         this._clientLog.debug(`connect enter: state=${this._state} aid=${this._aid ?? '-'}`);
-        if (this._state !== 'idle' && this._state !== 'closed' && this._state !== 'disconnected') {
+        if (arguments.length > 1) {
+            throw new ValidationError('connect accepts a single options object');
+        }
+        if ('aid' in options || 'access_token' in options || 'token' in options || 'kite_token' in options) {
+            throw new ValidationError('connect options must not include aid or token fields; load an AID object first');
+        }
+        const target = this._currentAid?.aid ?? this._aid ?? '';
+        if (!target || !this._currentAid?.isPrivateKeyValid()) {
+            throw new StateError('connect requires a loaded AID with a valid private key');
+        }
+        const publicState = this.state;
+        const allowed = new Set([
+            ConnectionState.STANDBY,
+            ConnectionState.AUTHENTICATED,
+            ConnectionState.RETRY_BACKOFF,
+            ConnectionState.CONNECTION_FAILED,
+        ]);
+        if (!allowed.has(publicState)) {
             this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=invalid_state state=${this._state}`);
-            throw new StateError(`connect not allowed in state ${this._state}`);
+            throw new StateError(`connect not allowed in state ${publicState}`);
         }
         this._state = 'connecting';
-        const params = { ...auth, ...options };
+        const gateway = String(options.gateway ?? this._gatewayUrl ?? await this._resolveGatewayForAid(target)).trim();
+        const params = { ...options, gateway };
         const normalized = this._normalizeConnectParams(params);
         this._sessionParams = normalized;
         this._sessionOptions = this._buildSessionOptions(normalized);
@@ -1286,7 +1742,7 @@ export class AUNClient {
         for (const gw of gateways) {
             try {
                 const gwParams = { ...normalized, gateway: gw };
-                await this._connectOnce(gwParams, false);
+                await this._connectOnce(gwParams, true);
                 this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms state=${this._state}`);
                 return;
             }
@@ -1301,7 +1757,7 @@ export class AUNClient {
             }
         }
         if (this._state === 'connecting' || this._state === 'authenticating') {
-            this._state = 'disconnected';
+            this._state = 'terminal_failed';
         }
         this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
         throw lastErr;
@@ -1323,56 +1779,9 @@ export class AUNClient {
         }
         await this._transport.close();
         this._state = 'disconnected';
-        await this._dispatcher.publish('connection.state', { state: this._state });
+        await this._dispatcher.publish('connection.state', { state: this._publicState(this._state) });
         this._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms`);
     }
-    /** 列出本地所有已存储的身份摘要（仅返回有有效私钥的 AID） */
-    async listIdentities() {
-        const tStart = Date.now();
-        this._clientLog.debug('listIdentities enter');
-        try {
-            const listFn = this._keystore.listIdentities;
-            if (typeof listFn !== 'function') {
-                this._clientLog.debug(`listIdentities exit: elapsed=${Date.now() - tStart}ms count=0 reason=keystore_no_list`);
-                return [];
-            }
-            const aids = await listFn.call(this._keystore);
-            const summaries = [];
-            for (const aid of [...aids].sort()) {
-                const identity = await this._keystore.loadIdentity(aid);
-                if (!identity || !identity.private_key_pem)
-                    continue;
-                const summary = { aid };
-                // 优先从 loadMetadata 获取
-                const loadMeta = this._keystore.loadMetadata;
-                if (typeof loadMeta === 'function') {
-                    const md = await loadMeta.call(this._keystore, aid);
-                    if (md && Object.keys(md).length > 0) {
-                        summary.metadata = md;
-                    }
-                }
-                // 回退：从 identity 中提取非核心字段
-                if (!summary.metadata) {
-                    const metadata = {};
-                    for (const [key, value] of Object.entries(identity)) {
-                        if (!['aid', 'private_key_pem', 'public_key_der_b64', 'curve', 'cert'].includes(key)) {
-                            metadata[key] = value;
-                        }
-                    }
-                    if (Object.keys(metadata).length > 0) {
-                        summary.metadata = metadata;
-                    }
-                }
-                summaries.push(summary);
-            }
-            this._clientLog.debug(`listIdentities exit: elapsed=${Date.now() - tStart}ms count=${summaries.length}`);
-            return summaries;
-        }
-        catch (err) {
-            this._clientLog.debug(`listIdentities exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
-        }
-    }
     /** 关闭连接 */
     async close() {
         const tStart = Date.now();
@@ -1401,7 +1810,7 @@ export class AUNClient {
         }
         await this._transport.close();
         this._state = 'closed';
-        await this._dispatcher.publish('connection.state', { state: this._state });
+        await this._dispatcher.publish('connection.state', { state: this._publicState(this._state) });
         this._resetSeqTrackingState();
         this._clientLog.debug(`close exit: elapsed=${Date.now() - tStart}ms`);
     }
@@ -1436,6 +1845,10 @@ export class AUNClient {
             throw new PermissionError(`legacy E2EE method is removed in this SDK: ${method}`);
         }
         const p = { ...(params ?? {}) };
+        if (this._instanceProtectedHeaders && PROTECTED_HEADERS_METHODS.has(method)) {
+            const existing = isJsonObject(p.protected_headers) ? p.protected_headers : {};
+            p.protected_headers = { ...this._instanceProtectedHeaders, ...existing };
+        }
         if (method === 'message.send' || method === 'group.send') {
             this._normalizeOutboundMessagePayload(p, method);
         }
@@ -1466,7 +1879,7 @@ export class AUNClient {
                     throw new StateError('V2 session not initialized; encrypted message.send requires V2 (V1 E2EE removed)');
                 }
                 this._clientLog.debug('call route: message.send → V2 encrypted send');
-                return await this.sendV2(String(p.to ?? ''), p.payload ?? {}, {
+                return await this._sendV2(String(p.to ?? ''), p.payload ?? {}, {
                     messageId: String(p.message_id ?? '') || undefined,
                     timestamp: p.timestamp,
                     protectedHeaders: this._protectedHeadersFromParams(p),
@@ -1485,7 +1898,7 @@ export class AUNClient {
                     throw new StateError('V2 session not initialized; encrypted group.send requires V2 (V1 E2EE removed)');
                 }
                 this._clientLog.debug('call route: group.send → V2 encrypted send');
-                return await this.sendGroupV2(String(p.group_id ?? ''), p.payload ?? {}, {
+                return await this._sendGroupV2(String(p.group_id ?? ''), p.payload ?? {}, {
                     messageId: String(p.message_id ?? '') || undefined,
                     timestamp: p.timestamp,
                     protectedHeaders: this._protectedHeadersFromParams(p),
@@ -1533,24 +1946,24 @@ export class AUNClient {
         // message.pull：V2 就绪时走 V2 pull
         if (method === 'message.pull' && this._v2Session) {
             this._clientLog.debug('call route: message.pull → V2 pull');
-            const messages = await this.pullV2(Number(p.after_seq ?? 0) || 0, Number(p.limit ?? 50) || 50);
+            const messages = await this._pullV2(Number(p.after_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, { force: p.force === true });
             return { messages };
         }
         // message.ack：V2 就绪时走 V2 ack
         if (method === 'message.ack' && this._v2Session) {
             this._clientLog.debug('call route: message.ack → V2 ack');
-            return await this.ackV2(Number(p.seq ?? p.up_to_seq ?? 0) || undefined);
+            return await this._ackV2(Number(p.seq ?? p.up_to_seq ?? 0) || undefined);
         }
         // group.pull：V2 就绪时走 V2 pull
         if (method === 'group.pull' && this._v2Session && p.group_id) {
             this._clientLog.debug('call route: group.pull → V2 pull');
-            const messages = await this.pullGroupV2(String(p.group_id), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50);
+            const messages = await this._pullGroupV2(String(p.group_id), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50);
             return { messages };
         }
         // group.ack_messages：V2 就绪时走 V2 ack
         if (method === 'group.ack_messages' && this._v2Session && p.group_id) {
             this._clientLog.debug('call route: group.ack_messages → V2 ack');
-            return await this.ackGroupV2(String(p.group_id), Number(p.seq ?? p.msg_seq ?? p.up_to_seq ?? 0) || undefined);
+            return await this._ackGroupV2(String(p.group_id), Number(p.seq ?? p.msg_seq ?? p.up_to_seq ?? 0) || undefined);
         }
         // 关键操作自动附加客户端签名
         if (SIGNED_METHODS.has(method)) {
@@ -1651,15 +2064,29 @@ export class AUNClient {
         // ── Group E2EE 自动编排已移除（V2-only：由 group.v2.bootstrap 驱动）────────
         return result;
     }
-    // ── 便利方法 ──────────────────────────────────────
-    async ping(params) {
-        return this.meta.ping(params);
-    }
-    async status(params) {
-        return this.meta.status(params);
-    }
-    async trustRoots(params) {
-        return this.meta.trustRoots(params);
+    async _callRawV2Rpc(method, params) {
+        const p = { ...(params ?? {}) };
+        delete p._pull_gate_locked;
+        delete p._skip_auto_ack;
+        delete p.skip_auto_ack;
+        if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
+            p.group_id = normalizeGroupId(String(p.group_id)) || String(p.group_id);
+        }
+        if (method.startsWith('group.') && p.device_id === undefined) {
+            p.device_id = this._deviceId;
+        }
+        if (method.startsWith('group.') && p.slot_id === undefined) {
+            p.slot_id = this._slotId;
+        }
+        if (SIGNED_METHODS.has(method)) {
+            if (this._shouldSkipClientSignature(method, p)) {
+                delete p.client_signature;
+            }
+            else {
+                await this._signClientOperation(method, p);
+            }
+        }
+        return await this._transport.call(method, p);
     }
     // ── 事件 ──────────────────────────────────────────
     /**
@@ -1695,12 +2122,19 @@ export class AUNClient {
             }
             // P2P 空洞检测
             const seq = msg.seq;
+            const encryptedPush = isEncryptedPushMessage(msg);
             if (seq !== undefined && seq !== null && this._aid) {
                 const ns = `p2p:${this._aid}`;
                 // Push 修上界：先更新 maxSeenSeq
                 if (seq > 0)
                     this._seqTracker.updateMaxSeen(ns, seq);
-                const needPull = this._seqTracker.onMessageSeq(ns, seq);
+                const contigBefore = this._seqTracker.getContiguousSeq(ns);
+                const seqNeedsPull = this._seqTracker.onMessageSeq(ns, seq);
+                const published = encryptedPush
+                    ? await this._publishEncryptedPushMessage('message.received', 'message.undecryptable', ns, seq, msg, false)
+                    : await this._publishOrderedMessage('message.received', ns, seq, msg);
+                const contigAfter = this._seqTracker.getContiguousSeq(ns);
+                const needPull = seqNeedsPull && !published;
                 if (needPull) {
                     this._safeAsync(this._fillP2pGap());
                 }
@@ -1716,14 +2150,16 @@ export class AUNClient {
                     }).catch((e) => { this._clientLog.warn(`P2P auto-ack failed:${String(e)}`); });
                 }
                 // 即时持久化 cursor，异常断连后不回退
-                this._saveSeqTrackerState();
-            }
-            // 明文消息直接透传
-            if (seq !== undefined && seq !== null && this._aid) {
-                const ns = `p2p:${this._aid}`;
-                await this._publishOrderedMessage('message.received', ns, seq, msg);
+                if (contigAfter !== contigBefore)
+                    this._saveSeqTrackerState();
+                if (encryptedPush)
+                    return;
             }
             else {
+                if (encryptedPush) {
+                    await this._publishEncryptedPushMessage('message.received', 'message.undecryptable', '', seq ?? 0, msg, false);
+                    return;
+                }
                 await this._publishAppEvent('message.received', msg);
             }
         }
@@ -1789,7 +2225,7 @@ export class AUNClient {
             this._gapFillDone.add(dedupKey);
             try {
                 this._clientLog.debug(`_onRawGroupV2MessageCreated -> group.v2.pull group=${groupId} after_seq=${afterSeq}`);
-                const messages = await this.pullGroupV2(groupId, afterSeq, 50);
+                const messages = await this._pullGroupV2(groupId, afterSeq, 50);
                 this._clientLog.debug(`_onRawGroupV2MessageCreated pulled ${messages.length} msgs for group=${groupId}`);
             }
             finally {
@@ -1830,12 +2266,19 @@ export class AUNClient {
                 return;
             }
             // seq 跟踪 + auto-ack
+            const encryptedPush = isEncryptedPushMessage(msg);
             if (groupId && seq !== undefined && seq !== null) {
                 const ns = `group:${groupId}`;
                 // Push 修上界：先更新 maxSeenSeq
                 if (seq > 0)
                     this._seqTracker.updateMaxSeen(ns, seq);
-                const needPull = this._seqTracker.onMessageSeq(ns, seq);
+                const contigBefore = this._seqTracker.getContiguousSeq(ns);
+                const seqNeedsPull = this._seqTracker.onMessageSeq(ns, seq);
+                const published = encryptedPush
+                    ? await this._publishEncryptedPushMessage('group.message_created', 'group.message_undecryptable', ns, seq, msg, true)
+                    : await this._publishOrderedMessage('group.message_created', ns, seq, msg);
+                const contigAfter = this._seqTracker.getContiguousSeq(ns);
+                const needPull = seqNeedsPull && !published;
                 if (needPull) {
                     this._safeAsync(this._fillGroupGap(groupId));
                 }
@@ -1850,14 +2293,16 @@ export class AUNClient {
                         slot_id: this._slotId,
                     }).catch((e) => { this._clientLog.warn('group message auto-ack failed: group=' + groupId, e); });
                 }
-                this._saveSeqTrackerState();
-            }
-            // 明文消息直接透传
-            if (groupId && seq !== undefined && seq !== null) {
-                const nsKey = `group:${groupId}`;
-                await this._publishOrderedMessage('group.message_created', nsKey, seq, msg);
+                if (contigAfter !== contigBefore)
+                    this._saveSeqTrackerState();
+                if (encryptedPush)
+                    return;
             }
             else {
+                if (encryptedPush) {
+                    await this._publishEncryptedPushMessage('group.message_created', 'group.message_undecryptable', '', seq ?? 0, msg, true);
+                    return;
+                }
                 await this._publishAppEvent('group.message_created', msg);
             }
         }
@@ -1878,6 +2323,59 @@ export class AUNClient {
             }
         }
     }
+    async _decryptEncryptedPushPayload(msg, group) {
+        const envelope = encryptedPushEnvelope(msg);
+        if (!isV2EncryptedEnvelopePayload(envelope))
+            return null;
+        const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
+        const fromAid = String(msg.from_aid ?? msg.from ?? msg.sender_aid ?? aad.from ?? '').trim();
+        const plaintext = await this._decryptV2EnvelopeForThought({ envelope, fromAid });
+        if (!plaintext)
+            return null;
+        const e2eeMeta = v2E2eeMeta(envelope);
+        const result = {
+            message_id: String(msg.message_id ?? ''),
+            from: fromAid,
+            seq: msg.seq ?? null,
+            timestamp: msg.t_server ?? msg.timestamp ?? null,
+            payload: plaintext,
+            encrypted: true,
+            e2ee: e2eeMeta,
+        };
+        result.direction = fromAid && fromAid === this._aid ? 'outbound_sync' : 'inbound';
+        if (msg.t_server !== undefined)
+            result.t_server = msg.t_server;
+        if (msg.device_id !== undefined)
+            result.device_id = msg.device_id;
+        if (msg.slot_id !== undefined)
+            result.slot_id = msg.slot_id;
+        if (group) {
+            result.group_id = msg.group_id ?? aad.group_id ?? envelope.group_id ?? null;
+        }
+        else {
+            result.to = msg.to ?? this._aid ?? '';
+        }
+        attachV2EnvelopeMetadata(result, e2eeMeta);
+        return result;
+    }
+    async _publishEncryptedPushAsUndecryptable(event, ns, seq, msg, group) {
+        const safeEvent = safeUndecryptablePushEvent(msg, group);
+        if (ns) {
+            return this._publishOrderedMessage(event, ns, seq, safeEvent);
+        }
+        await this._publishAppEvent(event, safeEvent);
+        return true;
+    }
+    async _publishEncryptedPushMessage(normalEvent, undecryptableEvent, ns, seq, msg, group) {
+        const decrypted = await this._decryptEncryptedPushPayload(msg, group);
+        if (decrypted) {
+            if (ns)
+                return this._publishOrderedMessage(normalEvent, ns, seq, decrypted);
+            await this._publishAppEvent(normalEvent, decrypted);
+            return true;
+        }
+        return this._publishEncryptedPushAsUndecryptable(undecryptableEvent, ns, seq, msg, group);
+    }
     /** 收到不带 payload 的 group.message_created 通知后，自动 pull 最新消息 */
     async _autoPullGroupMessages(notification) {
         const groupId = (notification.group_id ?? '');
@@ -3199,7 +3697,7 @@ export class AUNClient {
             this._state = 'connected';
             this._connectedAt = Date.now();
             await this._dispatcher.publish('connection.state', {
-                state: this._state,
+                state: this._publicState(this._state),
                 gateway: gatewayUrl,
             });
             if (this._seqTrackerContext !== this._currentSeqTrackerContext()) {
@@ -3209,7 +3707,7 @@ export class AUNClient {
             this._startBackgroundTasks();
             // V2 E2EE: 初始化 session 并注册设备 SPK（与 Python `_init_v2_session` 对齐）
             try {
-                await this.initV2Session();
+                await this._initV2Session();
             }
             catch (exc) {
                 this._clientLog.warn(`V2 session init failed (non-fatal): ${String(exc)}`);
@@ -3228,6 +3726,57 @@ export class AUNClient {
         const gateways = this._resolveGateways(params);
         return gateways[0];
     }
+    async _resolveGatewayForAid(aid) {
+        const target = String(aid ?? this._aid ?? '').trim();
+        if (!target)
+            throw new StateError('gateway discovery requires a loaded AID');
+        if (this._gatewayUrl)
+            return this._gatewayUrl;
+        try {
+            const getMetadata = this._keystore.getMetadata;
+            const raw = typeof getMetadata === 'function'
+                ? String(await getMetadata.call(this._keystore, target, 'gateway_url') ?? '').trim()
+                : '';
+            if (raw) {
+                const gateway = raw.startsWith('"') && raw.endsWith('"') ? String(JSON.parse(raw)).trim() : raw;
+                if (gateway) {
+                    this._gatewayUrl = gateway;
+                    return gateway;
+                }
+            }
+        }
+        catch {
+            // 缓存读取失败不影响发现流程。
+        }
+        const dotIdx = target.indexOf('.');
+        const issuerDomain = dotIdx >= 0 ? target.slice(dotIdx + 1) : target;
+        const portSuffix = this.configModel.discoveryPort ? `:${this.configModel.discoveryPort}` : '';
+        const candidates = [
+            `https://${target}${portSuffix}/.well-known/aun-gateway`,
+            `https://gateway.${issuerDomain}${portSuffix}/.well-known/aun-gateway`,
+        ];
+        let lastError = null;
+        for (const url of candidates) {
+            try {
+                const gateway = await this._discovery.discover(url);
+                this._gatewayUrl = gateway;
+                try {
+                    const setMetadata = this._keystore.setMetadata;
+                    if (typeof setMetadata === 'function') {
+                        await setMetadata.call(this._keystore, target, 'gateway_url', gateway);
+                    }
+                }
+                catch {
+                    // 缓存写入失败不影响连接。
+                }
+                return gateway;
+            }
+            catch (err) {
+                lastError = err;
+            }
+        }
+        throw lastError instanceof Error ? lastError : new ConnectionError(`gateway discovery failed for ${target}`);
+    }
     _resolveGateways(params) {
         const topology = isJsonObject(params.topology) ? params.topology : null;
         if (topology) {
@@ -3277,12 +3826,13 @@ export class AUNClient {
     _normalizeConnectParams(params) {
         const request = { ...params };
         const accessToken = String(request.access_token ?? '');
-        if (!accessToken)
-            throw new StateError('connect requires non-empty access_token');
         const gateway = String(request.gateway ?? this._gatewayUrl ?? '');
         if (!gateway)
             throw new StateError('connect requires non-empty gateway');
-        request.access_token = accessToken;
+        if (accessToken)
+            request.access_token = accessToken;
+        else
+            delete request.access_token;
         request.gateway = gateway;
         request.device_id = this._deviceId;
         request.slot_id = normalizeInstanceId(request.slot_id ?? this._slotId, 'slot_id', { allowEmpty: true });
@@ -3502,6 +4052,11 @@ export class AUNClient {
                 }
                 try {
                     identity = await this._auth.refreshCachedTokens(this._gatewayUrl, identity);
+                    // 刷新期间可能已断线，复检状态，避免写回 stale identity
+                    if (this._state !== 'connected') {
+                        scheduleRefresh();
+                        return;
+                    }
                     this._identity = identity;
                     if (this._sessionParams && identity.access_token) {
                         this._sessionParams.access_token = identity.access_token;
@@ -3642,7 +4197,7 @@ export class AUNClient {
         // 先停止后台任务，避免心跳/token刷新在重连期间继续触发
         this._stopBackgroundTasks();
         await this._dispatcher.publish('connection.state', {
-            state: this._state,
+            state: this._publicState(this._state),
             error,
         });
         if (!this._sessionOptions.auto_reconnect)
@@ -3656,7 +4211,7 @@ export class AUNClient {
             this._clientLog.warn(`suppress auto-reconnect: ${reason}`);
             const disconnectInfo = this._lastDisconnectInfo ?? {};
             const eventPayload = {
-                state: this._state, error, reason,
+                state: this._publicState(this._state), error, reason,
             };
             // 把服务端附带的结构化 detail（如配额超限信息）也带给应用层
             const detail = disconnectInfo.detail;
@@ -3684,34 +4239,51 @@ export class AUNClient {
         const maxAttempts = Number.isFinite(maxAttemptsRaw) && maxAttemptsRaw > 0 ? Math.floor(maxAttemptsRaw) : 0;
         // 服务端主动关闭时从 16s 起跳，避免重连风暴；网络断开从 initial_delay 起跳
         let delay = clampReconnectDelaySeconds(serverInitiated ? 16.0 : retry.initial_delay, serverInitiated ? 16.0 : 1.0, maxBaseDelay);
+        this._retryAttempt = 0;
+        this._retryMaxAttempts = maxAttempts;
         for (let attempt = 1; !this._reconnectAbort?.signal.aborted; attempt++) {
             // R1 fix: max_attempts 检查在循环顶部，覆盖所有路径（含 health-fail）
             if (maxAttempts > 0 && attempt > maxAttempts) {
                 this._state = 'terminal_failed';
+                this._nextRetryAt = null;
                 this._reconnectActive = false;
                 this._reconnectAbort = null;
                 await this._dispatcher.publish('connection.state', {
-                    state: this._state,
+                    state: this._publicState(this._state),
                     attempt: attempt - 1,
                     reason: 'max_attempts_exhausted',
                 });
                 return;
             }
-            this._state = 'reconnecting';
+            // 先进入 retry_backoff 状态（对齐 Python：先退避再重连）
+            this._retryAttempt = attempt;
+            const sleepMs = reconnectSleepDelaySeconds(delay, maxBaseDelay) * 1000;
+            this._nextRetryAt = new Date(Date.now() + sleepMs);
+            this._state = 'retry_backoff';
             await this._dispatcher.publish('connection.state', {
-                state: this._state,
+                state: this._publicState(this._state),
                 attempt,
+                next_retry_at: this._nextRetryAt.getTime() / 1000,
             });
             try {
-                await this._sleep(reconnectSleepDelaySeconds(delay, maxBaseDelay) * 1000);
+                await this._sleep(sleepMs);
+                this._nextRetryAt = null;
                 if (this._reconnectAbort?.signal.aborted) {
                     this._reconnectActive = false;
                     return;
                 }
+                // 退避结束，进入 reconnecting 状态
+                this._state = 'reconnecting';
+                await this._dispatcher.publish('connection.state', {
+                    state: this._publicState(this._state),
+                    attempt,
+                });
                 // 重连前先 GET /health 探测，不健康则跳过本轮
                 if (this._gatewayUrl) {
                     const healthy = await this._discovery.checkHealth(this._gatewayUrl, 5000);
                     if (!healthy) {
+                        this._lastError = new Error('gateway health check failed');
+                        this._lastErrorCode = 'gateway_unhealthy';
                         delay = Math.min(delay * 2, maxBaseDelay);
                         continue;
                     }
@@ -3721,21 +4293,27 @@ export class AUNClient {
                     throw new StateError('missing connect params for reconnect');
                 }
                 await this._connectOnce(this._sessionParams, true);
+                this._lastError = null;
+                this._lastErrorCode = null;
+                this._nextRetryAt = null;
                 this._reconnectActive = false;
                 this._reconnectAbort = null;
                 return;
             }
             catch (exc) {
+                this._lastError = exc instanceof Error ? exc : new Error(String(exc));
+                this._lastErrorCode = 'reconnect_failed';
                 await this._dispatcher.publish('connection.error', {
                     error: formatCaughtError(exc),
                     attempt,
                 });
                 if (!this._shouldRetryReconnect(exc)) {
                     this._state = 'terminal_failed';
+                    this._nextRetryAt = null;
                     this._reconnectActive = false;
                     this._reconnectAbort = null;
                     await this._dispatcher.publish('connection.state', {
-                        state: this._state,
+                        state: this._publicState(this._state),
                         error: formatCaughtError(exc),
                         attempt,
                     });
@@ -4085,10 +4663,30 @@ export class AUNClient {
      *
      * connect 成功后自动调用，可幂等手动调用。
      */
-    async initV2Session() {
+    async _initV2Session() {
         if (!this._aid)
             return;
-        const identity = this._identity;
+        let identity = this._identity;
+        if (!identity?.private_key_pem) {
+            // fallback：缓存的 identity 可能被 instance_state 污染，重新从 keystore 加载
+            try {
+                const reloaded = await this._keystore.loadIdentity(this._aid);
+                if (reloaded?.private_key_pem) {
+                    this._identity = reloaded;
+                    identity = reloaded;
+                    this._clientLog.warn('V2 session init: identity cache was stale, reloaded from keystore');
+                    // 自愈：重新持久化，清理 instance_state 中的脏数据
+                    try {
+                        const persistIdentity = this._auth._persistIdentity;
+                        if (typeof persistIdentity === 'function') {
+                            await persistIdentity.call(this._auth, reloaded);
+                        }
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            catch { /* ignore */ }
+        }
         if (!identity?.private_key_pem) {
             this._clientLog.warn('V2 session init skipped: no AID private key');
             return;
@@ -4370,7 +4968,7 @@ export class AUNClient {
      * @param opts 可选 messageId / timestamp（与 Python 行为一致）
      * @returns 服务端响应
      */
-    async sendV2(to, payload, opts) {
+    async _sendV2(to, payload, opts) {
         if (!this._v2Session) {
             throw new StateError('V2 session not initialized (not connected?)');
         }
@@ -4414,20 +5012,21 @@ export class AUNClient {
      * @param afterSeq 从此 seq 之后开始拉取（0/省略 = 从当前 contiguous 开始）
      * @param limit 最多拉取条数
      */
-    async pullV2(afterSeq = 0, limit = 50) {
+    async _pullV2(afterSeq = 0, limit = 50, opts) {
         if (!this._v2Session) {
             throw new StateError('V2 session not initialized (not connected?)');
         }
         const ns = this._aid ? `p2p:${this._aid}` : '';
         const decrypted = [];
-        let nextAfterSeq = afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
+        let nextAfterSeq = opts?.force ? afterSeq : (afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0));
         let pageCount = 0;
         const maxPages = 100;
         while (pageCount < maxPages) {
             pageCount += 1;
-            const result = await this.call('message.v2.pull', {
+            const result = await this._callRawV2Rpc('message.v2.pull', {
                 after_seq: nextAfterSeq,
                 limit,
+                ...(opts?.force ? { force: true } : {}),
             });
             const messages = (Array.isArray(result?.messages) ? result.messages : []);
             const seqs = messages
@@ -4509,7 +5108,7 @@ export class AUNClient {
                     this._saveSeqTrackerState();
                 }
                 if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
-                    this._safeAsync(this.ackV2(ackSeq).then(() => undefined));
+                    this._safeAsync(this._ackV2(ackSeq).then(() => undefined));
                 }
             }
             const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
@@ -4527,7 +5126,7 @@ export class AUNClient {
      *
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
-    async ackV2(upToSeq) {
+    async _ackV2(upToSeq) {
         const ns = this._aid ? `p2p:${this._aid}` : '';
         let seq = upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
         if (seq <= 0)
@@ -4747,6 +5346,12 @@ export class AUNClient {
             encrypted: true,
             e2ee: e2ee,
         };
+        const explicitDirection = String(msg.direction ?? '').trim();
+        result.direction = explicitDirection || (fromAid && fromAid === this._aid ? 'outbound_sync' : 'inbound');
+        if (msg.device_id !== undefined)
+            result.device_id = msg.device_id;
+        if (msg.slot_id !== undefined)
+            result.slot_id = msg.slot_id;
         attachV2EnvelopeMetadata(result, e2ee);
         return result;
     }
@@ -4758,7 +5363,7 @@ export class AUNClient {
      * @param opts 可选 messageId / timestamp
      * @returns 服务端响应
      */
-    async sendGroupV2(groupId, payload, opts) {
+    async _sendGroupV2(groupId, payload, opts) {
         if (!this._v2Session) {
             throw new StateError('V2 session not initialized (not connected?)');
         }
@@ -4817,7 +5422,7 @@ export class AUNClient {
         }
     }
     async _pullGroupV2Internal(params) {
-        await this.pullGroupV2(params.group_id, params.after_seq, params.limit);
+        await this._pullGroupV2(params.group_id, params.after_seq, params.limit);
     }
     /**
      * 拉取并解密 V2 Group 消息。
@@ -4826,7 +5431,7 @@ export class AUNClient {
      * @param afterSeq 从此 seq 之后开始拉取（0/省略 = 从当前 contiguous 开始）
      * @param limit 最多拉取条数
      */
-    async pullGroupV2(groupId, afterSeq = 0, limit = 50) {
+    async _pullGroupV2(groupId, afterSeq = 0, limit = 50) {
         if (!this._v2Session) {
             throw new StateError('V2 session not initialized (not connected?)');
         }
@@ -4925,7 +5530,7 @@ export class AUNClient {
                 this._saveSeqTrackerState();
             }
             if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
-                this._safeAsync(this.ackGroupV2(gid, ackSeq).then(() => undefined));
+                this._safeAsync(this._ackGroupV2(gid, ackSeq).then(() => undefined));
             }
             const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
             if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
@@ -4943,7 +5548,7 @@ export class AUNClient {
      * @param groupId 群 ID
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
-    async ackGroupV2(groupId, upToSeq) {
+    async _ackGroupV2(groupId, upToSeq) {
         const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
         if (!gid)
             throw new ValidationError('group.ack_messages requires group_id');
@@ -6020,7 +6625,7 @@ export class AUNClient {
         try {
             do {
                 this._v2PullPending = false;
-                await this.pullV2();
+                await this._pullV2();
                 const newContig = ns ? this._seqTracker.getContiguousSeq(ns) : -1;
                 this._clientLog.debug(`_onV2PushNotification pull done: contiguous_seq=${contigBefore}->${newContig} (push_seq=${pushSeq || 'null'})`);
             } while (this._v2PullPending);