@agentunion/fastaun-browser 0.4.2 → 0.4.4

package/dist/bundle.js

@@ -454,7 +454,7 @@ var init_indexeddb_store = __esm({
 });
 
 // src/version.ts
-var VERSION = "0.4.2";
+var VERSION = "0.4.4";
 
 // src/types.ts
 var ConnectionState = /* @__PURE__ */ ((ConnectionState2) => {
@@ -708,6 +708,7 @@ function mapRemoteError(error) {
 
 // src/config.ts
 var INSTANCE_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+var SLOT_ID_PATTERN = /^[A-Za-z0-9._-][A-Za-z0-9._/ :-]{0,127}$/;
 function readString(value, fallback) {
   return typeof value === "string" ? value : fallback;
 }
@@ -731,6 +732,18 @@ function normalizeInstanceId(value, field, opts = {}) {
   }
   return text;
 }
+function normalizeSlotId(value, defaultValue = "default") {
+  const raw = String(value ?? "");
+  const text = raw || defaultValue;
+  if (!SLOT_ID_PATTERN.test(text)) {
+    throw new ValidationError("slot_id contains unsupported characters");
+  }
+  return text;
+}
+function slotIsolationKey(slotId) {
+  const m = slotId.match(/^[^/ :]+/);
+  return m ? m[0] : slotId;
+}
 function getDeviceId() {
   const STORAGE_KEY = "aun_device_id";
   try {
@@ -752,7 +765,8 @@ var DEFAULTS = {
   groupE2ee: true,
   verifySsl: true,
   requireForwardSecrecy: true,
-  replayWindowSeconds: 300
+  replayWindowSeconds: 300,
+  discoveryPort: null
 };
 function createConfig(raw) {
   const data = raw ?? {};
@@ -769,10 +783,10 @@ function createConfig(raw) {
       DEFAULTS.seedPassword
     ),
     groupE2ee: true,
-    // 必备能力，不可配置
     verifySsl: DEFAULTS.verifySsl,
     requireForwardSecrecy: readBoolean(data.requireForwardSecrecy ?? data.require_forward_secrecy, DEFAULTS.requireForwardSecrecy),
-    replayWindowSeconds: readOptionalNumber(data.replayWindowSeconds ?? data.replay_window_seconds, DEFAULTS.replayWindowSeconds) ?? DEFAULTS.replayWindowSeconds
+    replayWindowSeconds: readOptionalNumber(data.replayWindowSeconds ?? data.replay_window_seconds, DEFAULTS.replayWindowSeconds) ?? DEFAULTS.replayWindowSeconds,
+    discoveryPort: readOptionalNumber(data.discoveryPort ?? data.discovery_port, DEFAULTS.discoveryPort)
   };
 }
 
@@ -3128,6 +3142,9 @@ var _AuthFlow = class _AuthFlow {
         delete persistedRecord[key];
       }
     }
+    for (const key of ["private_key_pem", "public_key_der_b64", "curve"]) {
+      delete persistedRecord[key];
+    }
     await this._keystore.saveIdentity(aid, persisted);
     if (Object.keys(instanceState).length === 0 || typeof this._keystore.updateInstanceState !== "function") {
       return;
@@ -3594,8 +3611,8 @@ function certStoreKey(aid, certFingerprint) {
 }
 function instanceStateStoreKey(aid, deviceId, slotId = "") {
   const normalizedDevice = normalizeInstanceId(deviceId, "device_id");
-  const normalizedSlot = normalizeInstanceId(slotId, "slot_id", { allowEmpty: true }) || "_singleton";
-  return `${safeAid(aid)}|${encodePart(normalizedDevice)}|${encodePart(normalizedSlot)}`;
+  const slotKey = slotIsolationKey(slotId) || "_singleton";
+  return `${safeAid(aid)}|${encodePart(normalizedDevice)}|${encodePart(slotKey)}`;
 }
 function prekeyPrefix(aid) {
   return `${safeAid(aid)}|`;
@@ -3629,8 +3646,8 @@ function sessionStoreKey(aid, sessionId) {
 }
 function seqTrackerPrefix(aid, deviceId, slotId) {
   const normalizedDevice = normalizeInstanceId(deviceId, "device_id");
-  const normalizedSlot = normalizeInstanceId(slotId, "slot_id", { allowEmpty: true }) || "_singleton";
-  return `_seq_|${safeAid(aid)}|${encodePart(normalizedDevice)}|${encodePart(normalizedSlot)}|`;
+  const slotKey = slotIsolationKey(slotId) || "_singleton";
+  return `_seq_|${safeAid(aid)}|${encodePart(normalizedDevice)}|${encodePart(slotKey)}|`;
 }
 function seqTrackerStoreKey(aid, deviceId, slotId, namespace) {
   return `${seqTrackerPrefix(aid, deviceId, slotId)}${encodePart(namespace)}`;
@@ -9689,7 +9706,8 @@ var AID = class _AID {
     __publicField(this, "verifySsl");
     __publicField(this, "rootCaPath");
     __publicField(this, "debug");
-    __publicField(this, "_privateKeyPem");
+    /** AIDStore 加载时注入的明文私钥 PEM，供 AUNClient 直接使用（无需 seed）。*/
+    __publicField(this, "privateKeyPem");
     __publicField(this, "_certValid");
     __publicField(this, "_privateKeyValid");
     __publicField(this, "_certFingerprint", "");
@@ -9707,7 +9725,7 @@ var AID = class _AID {
     this.certIssuer = meta.issuer;
     this.certNotBefore = meta.notBefore;
     this.certNotAfter = meta.notAfter;
-    this._privateKeyPem = params.privateKeyPem;
+    this.privateKeyPem = params.privateKeyPem ?? "";
     this._certValid = params.certValid;
     this._privateKeyValid = params.privateKeyValid;
   }
@@ -9726,10 +9744,10 @@ var AID = class _AID {
     return this._privateKeyValid;
   }
   async sign(payload) {
-    if (!this._privateKeyValid || !this._privateKeyPem) return resultErr(PRIVATE_KEY_NOT_VALID, "private key is not valid");
+    if (!this._privateKeyValid || !this.privateKeyPem) return resultErr(PRIVATE_KEY_NOT_VALID, "private key is not valid");
     try {
       const data = typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
-      return resultOk({ signature: await signBytes(this._privateKeyPem, data) });
+      return resultOk({ signature: await signBytes(this.privateKeyPem, data) });
     } catch (exc) {
       return resultErr(SIGNATURE_OPERATION_ERROR, String(exc), exc);
     }
@@ -9744,10 +9762,10 @@ var AID = class _AID {
     }
   }
   async signAgentMd(content) {
-    if (!this._privateKeyValid || !this._privateKeyPem) return resultErr(PRIVATE_KEY_NOT_VALID, "private key is not valid");
+    if (!this._privateKeyValid || !this.privateKeyPem) return resultErr(PRIVATE_KEY_NOT_VALID, "private key is not valid");
     try {
       const payload = normalizeAgentMdPayload(content);
-      const signature = await signBytes(this._privateKeyPem, new TextEncoder().encode(payload));
+      const signature = await signBytes(this.privateKeyPem, new TextEncoder().encode(payload));
       return resultOk({ signed: payload + buildAgentMdSignatureBlock(this.certFingerprint, Date.now() / 1e3, signature) });
     } catch (exc) {
       return resultErr(SIGNATURE_OPERATION_ERROR, String(exc), exc);
@@ -9795,6 +9813,12 @@ function getV2DeviceId(dev) {
   }
   return { present: false, value: "" };
 }
+function isAIDObject(value) {
+  const candidate = value;
+  return Boolean(
+    candidate && typeof candidate === "object" && typeof candidate.aid === "string" && typeof candidate.aunPath === "string" && typeof candidate.isPrivateKeyValid === "function"
+  );
+}
 function sortObjectKeys(obj) {
   if (obj === null || obj === void 0 || typeof obj !== "object") return obj;
   if (Array.isArray(obj)) return obj.map(sortObjectKeys);
@@ -9927,6 +9951,20 @@ var DEFAULT_SESSION_OPTIONS = {
     http: 30
   }
 };
+var PUBLIC_CONNECTION_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "auto_reconnect",
+  "connect_timeout",
+  "retry_initial_delay",
+  "retry_max_delay",
+  "retry_max_attempts",
+  "heartbeat_interval",
+  "call_timeout",
+  "connection_kind",
+  "short_ttl_ms",
+  "delivery_mode",
+  "extra_info",
+  "background_sync"
+]);
 var PROTECTED_HEADERS_METHODS = /* @__PURE__ */ new Set([
   "message.send",
   "group.send",
@@ -10308,15 +10346,6 @@ function normalizeDeliveryModeConfig(raw, opts = {}) {
     affinity_ttl_ms: affinityTtlMs
   };
 }
-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;
-}
 var _AUNClient = class _AUNClient {
   constructor(aid) {
     /** SDK 配置模型 */
@@ -10353,6 +10382,7 @@ var _AUNClient = class _AUNClient {
     // V2 E2EE 状态
     __publicField(this, "_v2Session");
     __publicField(this, "_v2KeyStore");
+    __publicField(this, "_v2SessionInitInFlight", null);
     __publicField(this, "_v2BootstrapCache", /* @__PURE__ */ new Map());
     __publicField(this, "_v2SenderIKPending", /* @__PURE__ */ new Map());
     __publicField(this, "_v2SenderIKFetching", /* @__PURE__ */ new Set());
@@ -10428,16 +10458,15 @@ var _AUNClient = class _AUNClient {
      */
     __publicField(this, "_v2PullInflight", false);
     __publicField(this, "_v2PullPending", false);
-    const inputAid = aid instanceof AID ? aid : null;
-    if (typeof aid === "string") {
-      throw new ValidationError("AUNClient aid must be an AID object, not a string");
+    if (aid !== null && aid !== void 0 && !isAIDObject(aid)) {
+      throw new ValidationError("AUNClient only accepts an AID object or no argument");
     }
-    const options = {};
-    const rawConfig = clientOptionsConfig(options);
+    const inputAid = aid ?? null;
+    const rawConfig = {};
     if (inputAid) rawConfig.aun_path = inputAid.aunPath;
-    const _debug = false;
+    const _debug = inputAid ? inputAid.debug : false;
     this.configModel = createConfig(rawConfig);
-    const initAid = inputAid ? inputAid.aid : null;
+    const initAid = inputAid && inputAid.isPrivateKeyValid() ? inputAid.aid : null;
     this.config = {
       aun_path: this.configModel.aunPath,
       root_ca_path: this.configModel.rootCaPem,
@@ -10456,7 +10485,7 @@ var _AUNClient = class _AUNClient {
     this._clientLog.info(`AUNClient initialized: debug=${_debug} aunPath=${this.configModel.aunPath} aid=${initAid ?? "-"}`);
     this._dispatcher = new EventDispatcher();
     this._discovery = new GatewayDiscovery();
-    this._keystore = new IndexedDBKeyStore({ encryptionSeed: this.configModel.seedPassword ?? void 0 });
+    this._keystore = new IndexedDBKeyStore({});
     this._slotId = inputAid?.slotId || "default";
     this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: "fanout" });
     this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -10481,18 +10510,16 @@ var _AUNClient = class _AUNClient {
       });
     });
     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 !== void 0) {
-      this.setProtectedHeaders(options.protected_headers);
+      if (inputAid.isPrivateKeyValid()) {
+        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";
+      }
     }
     this._auth.setLogger(this._logAuth);
     this._transport.setLogger(this._logTransport);
@@ -10718,7 +10745,7 @@ var _AUNClient = class _AUNClient {
    */
   async publishAgentMd(content) {
     const target = this._agentMdOwnerAid();
-    if (!target) {
+    if (!target || !this._currentAid) {
       throw new ValidationError("publishAgentMd requires local AID");
     }
     if (content !== void 0 && content !== null) {
@@ -11213,21 +11240,78 @@ var _AUNClient = class _AUNClient {
   get lastErrorCode() {
     return this._lastErrorCode;
   }
+  _applyAidRuntimeContext(aid) {
+    const nextConfig = createConfig({
+      aunPath: aid.aunPath,
+      rootCaPem: aid.rootCaPath,
+      verifySsl: aid.verifySsl
+    });
+    Object.assign(this.configModel, nextConfig);
+    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;
+    this._deviceId = aid.deviceId || getDeviceId();
+    this._slotId = aid.slotId || "default";
+    this._logger = new AUNLogger({ debug: aid.debug, aunPath: nextConfig.aunPath });
+    this._logger.bindDeviceId(this._deviceId);
+    this._clientLog = this._logger.for("aun_core.client");
+    this._logAuth = this._logger.for("aun_core.auth");
+    this._logTransport = this._logger.for("aun_core.transport");
+    this._logKeystore = this._logger.for("aun_core.keystore");
+    this._logDiscovery = this._logger.for("aun_core.discovery");
+    this._logEvents = this._logger.for("aun_core.events");
+    this._discovery = new GatewayDiscovery();
+    this._keystore = new IndexedDBKeyStore({});
+    this._auth = new AuthFlow({
+      keystore: this._keystore,
+      crypto: new CryptoProvider(),
+      aid: aid.aid,
+      deviceId: this._deviceId,
+      slotId: this._slotId,
+      rootCaPem: nextConfig.rootCaPem,
+      verifySsl: nextConfig.verifySsl
+    });
+    this._transport = new RPCTransport({
+      eventDispatcher: this._dispatcher,
+      timeout: DEFAULT_SESSION_OPTIONS.timeouts.call,
+      onDisconnect: (error, closeCode) => this._handleTransportDisconnect(error, closeCode)
+    });
+    this._transport.setMetaObserver((meta) => {
+      void this._observeRpcMeta(meta).catch((exc) => {
+        this._clientLog.debug(`agent.md meta observer skipped: ${String(exc)}`);
+      });
+    });
+    this._auth.setLogger(this._logAuth);
+    this._transport.setLogger(this._logTransport);
+    this._dispatcher.setLogger(this._logEvents);
+    if (typeof this._discovery.setLogger === "function") {
+      this._discovery.setLogger(this._logDiscovery);
+    }
+    if (typeof this._keystore.setLogger === "function") {
+      this._keystore.setLogger(this._logKeystore);
+    }
+  }
   loadIdentity(aid) {
     if (!aid?.isPrivateKeyValid()) throw new StateError("loadIdentity requires an AID with a valid private key");
     const publicState = this.state;
     if (publicState !== "no_identity" /* NO_IDENTITY */ && publicState !== "closed" /* CLOSED */) {
       throw new StateError(`loadIdentity not allowed in state ${publicState}`);
     }
+    this._applyAidRuntimeContext(aid);
     this._currentAid = aid;
     this._aid = aid.aid;
     this._identity = {
       aid: aid.aid,
-      private_key_pem: aid._privateKeyPem ?? "",
+      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;
   }
@@ -11271,9 +11355,6 @@ var _AUNClient = class _AUNClient {
   get gatewayUrl() {
     return this._gatewayUrl;
   }
-  set gatewayUrl(url) {
-    this._gatewayUrl = url;
-  }
   get discovery() {
     return this._discovery;
   }
@@ -11314,6 +11395,17 @@ var _AUNClient = class _AUNClient {
   /** 连接到 Gateway；身份来自构造函数或 loadIdentity(aid)，认证由 SDK 内部自动完成。 */
   async connect(opts) {
     const tStart = Date.now();
+    if (opts !== void 0 && opts !== null && typeof opts === "object") {
+      const raw = opts;
+      const invalid = Object.keys(raw).filter((key) => !PUBLIC_CONNECTION_OPTION_KEYS.has(key)).sort();
+      if (invalid.length > 0) {
+        throw new ValidationError(`connect options contain unsupported field(s): ${invalid.join(", ")}`);
+      }
+    }
+    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 options = {};
     if (opts?.auto_reconnect !== void 0) options.auto_reconnect = opts.auto_reconnect;
     if (opts?.heartbeat_interval !== void 0) options.heartbeat_interval = opts.heartbeat_interval;
@@ -11330,11 +11422,12 @@ var _AUNClient = class _AUNClient {
         max_attempts: opts.retry_max_attempts ?? 0
       };
     }
+    if (opts?.connection_kind !== void 0) options.connection_kind = opts.connection_kind;
+    if (opts?.short_ttl_ms !== void 0) options.short_ttl_ms = opts.short_ttl_ms;
+    if (opts?.delivery_mode !== void 0) options.delivery_mode = opts.delivery_mode;
+    if (opts?.extra_info !== void 0) options.extra_info = opts.extra_info;
+    if (opts?.background_sync !== void 0) options.background_sync = opts.background_sync;
     this._clientLog.debug(`connect enter: state=${this._state} aid=${this._aid ?? "-"}`);
-    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 = /* @__PURE__ */ new Set([
       "standby" /* STANDBY */,
@@ -11468,6 +11561,12 @@ var _AUNClient = class _AUNClient {
     }
     this._validateOutboundCall(method, p);
     this._injectMessageCursorContext(method, p);
+    if (method.startsWith("group.") && !("_group_cursor_params" in p) && !Boolean(p._pull_gate_locked)) {
+      const explicitCursorParams = this._groupCursorParams(p);
+      if (Object.keys(explicitCursorParams).length > 0) {
+        p._group_cursor_params = explicitCursorParams;
+      }
+    }
     if (method.startsWith("group.") && p.group_id !== void 0 && p.group_id !== null) {
       const rawGroupId = String(p.group_id);
       const normalizedGroupId = normalizeGroupId(rawGroupId);
@@ -11486,9 +11585,10 @@ var _AUNClient = class _AUNClient {
       const encrypt = p.encrypt !== void 0 ? p.encrypt : true;
       delete p.encrypt;
       if (encrypt) {
-        if (!this._v2Session) {
-          throw new StateError("V2 session not initialized; encrypted message.send requires V2 (V1 E2EE removed)");
-        }
+        await this._ensureV2SessionReady(
+          "message.send",
+          "V2 session not initialized; encrypted message.send requires V2 (V1 E2EE removed)"
+        );
         this._clientLog.debug("call route: message.send \u2192 V2 encrypted send");
         return await this._sendV2(String(p.to ?? ""), p.payload ?? {}, {
           messageId: String(p.message_id ?? "") || void 0,
@@ -11503,9 +11603,10 @@ var _AUNClient = class _AUNClient {
       const encrypt = p.encrypt !== void 0 ? p.encrypt : true;
       delete p.encrypt;
       if (encrypt) {
-        if (!this._v2Session) {
-          throw new StateError("V2 session not initialized; encrypted group.send requires V2 (V1 E2EE removed)");
-        }
+        await this._ensureV2SessionReady(
+          "group.send",
+          "V2 session not initialized; encrypted group.send requires V2 (V1 E2EE removed)"
+        );
         this._clientLog.debug("call route: group.send \u2192 V2 encrypted send");
         return await this._sendGroupV2(String(p.group_id ?? ""), p.payload ?? {}, {
           messageId: String(p.message_id ?? "") || void 0,
@@ -11520,9 +11621,10 @@ var _AUNClient = class _AUNClient {
       const encrypt = p.encrypt !== void 0 ? p.encrypt : true;
       delete p.encrypt;
       if (encrypt) {
-        if (!this._v2Session) {
-          throw new StateError("V2 session not initialized; encrypted group.thought.put requires V2 (V1 E2EE removed)");
-        }
+        await this._ensureV2SessionReady(
+          "group.thought.put",
+          "V2 session not initialized; encrypted group.thought.put requires V2 (V1 E2EE removed)"
+        );
         this._clientLog.debug("call route: group.thought.put \u2192 V2 encrypted put");
         return this._putGroupThoughtEncryptedV2(p);
       }
@@ -11531,9 +11633,10 @@ var _AUNClient = class _AUNClient {
       const encrypt = p.encrypt !== void 0 ? p.encrypt : true;
       delete p.encrypt;
       if (encrypt) {
-        if (!this._v2Session) {
-          throw new StateError("V2 session not initialized; encrypted message.thought.put requires V2 (V1 E2EE removed)");
-        }
+        await this._ensureV2SessionReady(
+          "message.thought.put",
+          "V2 session not initialized; encrypted message.thought.put requires V2 (V1 E2EE removed)"
+        );
         this._clientLog.debug("call route: message.thought.put \u2192 V2 encrypted put");
         return this._putMessageThoughtEncryptedV2(p);
       }
@@ -11551,26 +11654,43 @@ var _AUNClient = class _AUNClient {
    * 拆分出来以便 pull gate 包裹整个操作。
    */
   async _callImplInner(method, p) {
-    if (method === "message.pull" && this._v2Session) {
+    if (method === "message.pull") {
+      await this._ensureV2SessionReady("message.pull");
       this._clientLog.debug("call route: message.pull \u2192 V2 pull");
       const messages = await this._pullV2(Number(p.after_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, { force: p.force === true });
       return { messages };
     }
-    if (method === "message.ack" && this._v2Session) {
+    if (method === "message.ack") {
+      await this._ensureV2SessionReady("message.ack");
       this._clientLog.debug("call route: message.ack \u2192 V2 ack");
       return await this._ackV2(Number(p.seq ?? p.up_to_seq ?? 0) || void 0);
     }
-    if (method === "group.pull" && this._v2Session && p.group_id) {
+    if (method === "group.pull" && p.group_id) {
+      await this._ensureV2SessionReady("group.pull");
       this._clientLog.debug("call route: group.pull \u2192 V2 pull");
+      const hasExplicitAfterSeq = "after_seq" in p || "after_message_seq" in p;
+      const cursorParams = this._explicitGroupCursorParams(p);
+      const ownsCursor = Object.keys(cursorParams).length === 0 || this._groupCursorTargetsCurrentInstance(cursorParams);
+      const pullOpts = {};
+      if (hasExplicitAfterSeq) pullOpts.explicitAfterSeq = true;
+      if (Object.keys(cursorParams).length > 0) pullOpts.cursorParams = cursorParams;
+      if (!ownsCursor) pullOpts.ownsCursor = false;
       const messages = await this._pullGroupV2(
         String(p.group_id),
         Number(p.after_seq ?? p.after_message_seq ?? 0) || 0,
-        Number(p.limit ?? 50) || 50
+        Number(p.limit ?? 50) || 50,
+        Object.keys(pullOpts).length > 0 ? pullOpts : void 0
       );
       return { messages };
     }
-    if (method === "group.ack_messages" && this._v2Session && p.group_id) {
+    if (method === "group.ack_messages" && p.group_id) {
+      await this._ensureV2SessionReady("group.ack_messages");
       this._clientLog.debug("call route: group.ack_messages \u2192 V2 ack");
+      const cursorParams = this._explicitGroupCursorParams(p);
+      const ownsCursor = Object.keys(cursorParams).length === 0 || this._groupCursorTargetsCurrentInstance(cursorParams);
+      if (!ownsCursor) {
+        return await this._rawGroupAckMessages(p);
+      }
       return await this._ackGroupV2(
         String(p.group_id),
         Number(p.seq ?? p.msg_seq ?? p.up_to_seq ?? 0) || void 0
@@ -11671,6 +11791,7 @@ var _AUNClient = class _AUNClient {
     delete p._pull_gate_locked;
     delete p._skip_auto_ack;
     delete p.skip_auto_ack;
+    delete p._group_cursor_params;
     if (method.startsWith("group.") && p.group_id !== void 0 && p.group_id !== null) {
       p.group_id = normalizeGroupId(String(p.group_id)) || String(p.group_id);
     }
@@ -12000,54 +12121,27 @@ var _AUNClient = class _AUNClient {
   /** 后台补齐群消息空洞 */
   async _fillGroupGap(groupId) {
     if (this._state !== "connected" || this._closing) return;
+    groupId = normalizeGroupId(groupId) || String(groupId ?? "").trim();
+    if (!groupId) return;
     const ns = `group:${groupId}`;
     const afterSeq = this._seqTracker.getContiguousSeq(ns);
     const dedupKey = `group_pull:${ns}`;
     if (this._gapFillDone.has(dedupKey)) return;
     this._gapFillDone.add(dedupKey);
     this._gapFillActive = true;
+    let filled = 0;
     try {
-      const result = await this.call("group.pull", {
-        group_id: groupId,
-        after_message_seq: afterSeq,
-        device_id: this._deviceId,
-        limit: 50
-      });
-      if (isJsonObject(result)) {
-        const messages = result.messages;
-        if (Array.isArray(messages)) {
-          const pushed = this._pushedSeqs.get(ns);
-          for (const msg of messages) {
-            if (isJsonObject(msg)) {
-              const s = msg.seq;
-              if (pushed && s !== void 0 && s !== null && pushed.has(s)) continue;
-              if (s !== void 0 && s !== null) {
-                await this._publishPulledMessage("group.message_created", ns, s, msg);
-              } else {
-                await this._publishAppEvent("group.message_created", msg);
-              }
-            }
-          }
-          this._prunePushedSeqs(ns);
-          const contig = this._seqTracker.getContiguousSeq(ns);
-          if (contig > 0) {
-            const gid = groupId;
-            this._transport.call("group.ack_messages", {
-              group_id: gid,
-              msg_seq: contig,
-              device_id: this._deviceId,
-              slot_id: this._slotId
-            }).catch((e) => {
-              this._clientLog.warn(`group gap-fill auto-ack failed: group=${gid}`, e);
-            });
-          }
-        }
-      }
+      const messages = await this._pullGroupV2(groupId, afterSeq, 50);
+      filled = messages.length;
+      this._prunePushedSeqs(ns);
     } catch (exc) {
       this._clientLog.warn(`group message gap-fill failed:${String(exc)}`);
     } finally {
       this._gapFillDone.delete(dedupKey);
       this._gapFillActive = false;
+      if (filled > 0 && this._seqTracker.getContiguousSeq(ns) > afterSeq) {
+        this._safeAsync(this._fillGroupGap(groupId));
+      }
     }
   }
   /** 后台补齐群事件空洞 */
@@ -12145,44 +12239,19 @@ var _AUNClient = class _AUNClient {
     if (this._gapFillDone.has(dedupKey)) return;
     this._gapFillDone.add(dedupKey);
     this._gapFillActive = true;
+    let filled = 0;
     try {
-      const result = await this.call("message.pull", {
-        after_seq: afterSeq,
-        limit: 50
-      });
-      if (isJsonObject(result)) {
-        const messages = result.messages;
-        if (Array.isArray(messages)) {
-          const pushed = this._pushedSeqs.get(ns);
-          for (const msg of messages) {
-            if (isJsonObject(msg)) {
-              const s = msg.seq;
-              if (pushed && s !== void 0 && s !== null && pushed.has(s)) continue;
-              if (s !== void 0 && s !== null) {
-                await this._publishPulledMessage("message.received", ns, s, msg);
-              } else {
-                await this._publishAppEvent("message.received", msg);
-              }
-            }
-          }
-          this._prunePushedSeqs(ns);
-          const contig = this._seqTracker.getContiguousSeq(ns);
-          if (contig > 0) {
-            this._transport.call("message.ack", {
-              seq: contig,
-              device_id: this._deviceId,
-              slot_id: this._slotId
-            }).catch((e) => {
-              this._clientLog.warn(`P2P gap-fill auto-ack failed:${String(e)}`);
-            });
-          }
-        }
-      }
+      const messages = await this._pullV2(afterSeq, 50);
+      filled = messages.length;
+      this._prunePushedSeqs(ns);
     } catch (exc) {
       this._clientLog.warn(`P2P message gap-fill failed:${String(exc)}`);
     } finally {
       this._gapFillDone.delete(dedupKey);
       this._gapFillActive = false;
+      if (filled > 0 && this._seqTracker.getContiguousSeq(ns) > afterSeq) {
+        this._safeAsync(this._fillP2pGap());
+      }
     }
   }
   /** 只按硬上限裁剪 published guard，不能按 contiguousSeq 清理。 */
@@ -12304,7 +12373,7 @@ var _AUNClient = class _AUNClient {
     }
     if ("slot_id" in message) {
       const targetSlotId = String(message.slot_id ?? "").trim();
-      if (targetSlotId !== this._slotId) {
+      if (slotIsolationKey(targetSlotId) !== slotIsolationKey(this._slotId)) {
         return false;
       }
     }
@@ -13025,10 +13094,10 @@ var _AUNClient = class _AUNClient {
    * 使用 SubtleCrypto 异步签名。
    */
   async _signClientOperation(method, params) {
-    const identity = this._identity;
-    if (!identity || !identity.private_key_pem) return;
+    const currentAid = this._currentAid;
+    if (!currentAid?.privateKeyPem) return;
     try {
-      const aid = identity.aid ?? "";
+      const aid = currentAid.aid;
       const ts = String(Math.floor(Date.now() / 1e3));
       const paramsForHash = {};
       for (const [k, v] of Object.entries(params)) {
@@ -13043,7 +13112,7 @@ var _AUNClient = class _AUNClient {
       );
       const paramsHash = Array.from(new Uint8Array(paramsHashBuf)).map((b) => b.toString(16).padStart(2, "0")).join("");
       const signData = new TextEncoder().encode(`${method}|${aid}|${ts}|${paramsHash}`);
-      const pkcs8 = pemToArrayBuffer(identity.private_key_pem);
+      const pkcs8 = pemToArrayBuffer(currentAid.privateKeyPem);
       const cryptoKey = await crypto.subtle.importKey(
         "pkcs8",
         pkcs8,
@@ -13058,7 +13127,7 @@ var _AUNClient = class _AUNClient {
       );
       const sigDer = p1363ToDer(new Uint8Array(sigP1363));
       let certFingerprint = "";
-      const certPem = identity.cert ?? "";
+      const certPem = currentAid.certPem;
       if (certPem) {
         const certDer = pemToArrayBuffer(certPem);
         const fpBuf = await crypto.subtle.digest("SHA-256", certDer);
@@ -13158,12 +13227,22 @@ var _AUNClient = class _AUNClient {
         await this._restoreSeqTrackerState();
       }
       this._startBackgroundTasks();
-      try {
-        await this._initV2Session();
-      } catch (exc) {
-        this._clientLog.warn(`V2 session init failed (non-fatal): ${String(exc)}`);
+      const connectionKind = String(params.connection_kind ?? "long");
+      const isShortConnection = connectionKind === "short";
+      if (!isShortConnection) {
+        try {
+          await this._initV2Session();
+        } catch (exc) {
+          this._clientLog.warn(`V2 session init failed (non-fatal): ${String(exc)}`);
+        }
+      } else {
+        this._clientLog.debug("V2 session init deferred for short connection");
+      }
+      const hasExplicitBackgroundSync = Object.prototype.hasOwnProperty.call(params, "background_sync");
+      const backgroundSyncEnabled = this._sessionOptions?.background_sync !== false && (!isShortConnection || hasExplicitBackgroundSync);
+      if (backgroundSyncEnabled) {
+        this._safeAsync(this._fillP2pGap());
       }
-      this._safeAsync(this._fillP2pGap());
       this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? "-"}`);
     } catch (err) {
       this._clientLog.debug(`_connectOnce exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
@@ -13268,7 +13347,7 @@ var _AUNClient = class _AUNClient {
     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 });
+    request.slot_id = normalizeSlotId(request.slot_id ?? this._slotId, this._slotId || "default");
     let deliveryModeRaw = request.delivery_mode;
     if (deliveryModeRaw == null) {
       deliveryModeRaw = { ...this._defaultConnectDeliveryMode };
@@ -13338,6 +13417,7 @@ var _AUNClient = class _AUNClient {
     if (isJsonObject(params.timeouts)) {
       Object.assign(options.timeouts, params.timeouts);
     }
+    if ("background_sync" in params) options.background_sync = Boolean(params.background_sync);
     return options;
   }
   // ── 内部：后台任务 ────────────────────────────────
@@ -14039,6 +14119,19 @@ var _AUNClient = class _AUNClient {
     );
     return repaired;
   }
+  async _ensureV2SessionReady(method, errorMessage) {
+    if (!this._v2Session) {
+      if (!this._v2SessionInitInFlight) {
+        this._v2SessionInitInFlight = this._initV2Session().finally(() => {
+          this._v2SessionInitInFlight = null;
+        });
+      }
+      await this._v2SessionInitInFlight;
+    }
+    if (!this._v2Session) {
+      throw new StateError(errorMessage ?? `V2 session not initialized; encrypted ${method} requires E2EE V2`);
+    }
+  }
   // ── V2 E2EE API（async，与 Python `client.py` `_init_v2_session` / `send_v2` / `pull_v2` / `ack_v2` 对齐） ──
   /**
    * 初始化 V2 session：从 AID PEM 私钥提取 raw scalar + DER 公钥，
@@ -14048,31 +14141,13 @@ var _AUNClient = class _AUNClient {
    */
   async _initV2Session() {
     if (!this._aid) return;
-    let identity = this._identity;
-    if (!identity?.private_key_pem) {
-      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");
-          try {
-            const persistIdentity = this._auth._persistIdentity;
-            if (typeof persistIdentity === "function") {
-              await persistIdentity.call(this._auth, reloaded);
-            }
-          } catch {
-          }
-        }
-      } catch {
-      }
-    }
-    if (!identity?.private_key_pem) {
+    const currentAid = this._currentAid;
+    if (!currentAid?.privateKeyPem) {
       this._clientLog.warn("V2 session init skipped: no AID private key");
       return;
     }
     if (this._v2Session) return;
-    const pem = String(identity.private_key_pem).trim();
+    const pem = currentAid.privateKeyPem.trim();
     const pemBody = pem.replace(/-----BEGIN [^-]+-----/g, "").replace(/-----END [^-]+-----/g, "").replace(/\s+/g, "");
     const pkcs8Der = _v2B64ToBytes(pemBody);
     const privKey = await crypto.subtle.importKey(
@@ -14444,6 +14519,7 @@ var _AUNClient = class _AUNClient {
           decrypted.push(plaintext);
         }
       }
+      const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, "server_ack_seq");
       const serverAckSeq = Number(result.server_ack_seq ?? 0);
       if (ns && Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
         const contig = this._seqTracker.getContiguousSeq(ns);
@@ -14459,7 +14535,8 @@ var _AUNClient = class _AUNClient {
           await this._drainOrderedMessages(ns);
           this._saveSeqTrackerState();
         }
-        if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+        const ackNeeded = messages.length > 0 && ackSeq > 0 && (contigAdvanced || hasServerAckSeq && ackSeq > serverAckSeq);
+        if (ackNeeded) {
           this._safeAsync(this._ackV2(ackSeq).then(() => void 0));
         }
       }
@@ -14488,7 +14565,7 @@ var _AUNClient = class _AUNClient {
         seq = maxSeen;
       }
     }
-    const raw = await this.call("message.v2.ack", { up_to_seq: seq });
+    const raw = await this._callRawV2Rpc("message.v2.ack", { up_to_seq: seq });
     const result = isJsonObject(raw) ? { ...raw } : { result: raw };
     let actualAckSeq = seq;
     if ("effective_ack_seq" in result) actualAckSeq = Number(result.effective_ack_seq ?? 0);
@@ -14758,7 +14835,7 @@ var _AUNClient = class _AUNClient {
    * @param afterSeq 从此 seq 之后开始拉取（0/省略 = 从当前 contiguous 开始）
    * @param limit 最多拉取条数
    */
-  async _pullGroupV2(groupId, afterSeq = 0, limit = 50) {
+  async _pullGroupV2(groupId, afterSeq = 0, limit = 50, opts) {
     if (!this._v2Session) {
       throw new StateError("V2 session not initialized (not connected?)");
     }
@@ -14766,15 +14843,18 @@ var _AUNClient = class _AUNClient {
     if (!gid) throw new ValidationError("group.pull requires group_id");
     const ns = `group:${gid}`;
     const decrypted = [];
-    let nextAfterSeq = afterSeq || this._seqTracker.getContiguousSeq(ns);
+    const cursorParams = opts?.cursorParams ?? {};
+    const ownsCursor = opts?.ownsCursor !== false;
+    let nextAfterSeq = opts?.explicitAfterSeq ? afterSeq : afterSeq || this._seqTracker.getContiguousSeq(ns);
     let pageCount = 0;
     const maxPages = 100;
     while (pageCount < maxPages) {
       pageCount += 1;
-      const result = await this.call("group.v2.pull", {
+      const result = await this._callRawV2Rpc("group.v2.pull", {
         group_id: gid,
         after_seq: nextAfterSeq,
-        limit
+        limit,
+        ...cursorParams
       });
       const messages = Array.isArray(result?.messages) ? result.messages : [];
       const seqs = messages.map((msg) => Number(msg.seq ?? 0)).filter((seq) => Number.isFinite(seq) && seq > 0);
@@ -14836,6 +14916,7 @@ var _AUNClient = class _AUNClient {
         decrypted.push(plaintext);
       }
       const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+      const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, "current_seq");
       const serverAckSeq = Number(cursor?.current_seq ?? 0);
       if (Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
         const contig = this._seqTracker.getContiguousSeq(ns);
@@ -14850,10 +14931,12 @@ var _AUNClient = class _AUNClient {
         await this._drainOrderedMessages(ns);
         this._saveSeqTrackerState();
       }
-      if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+      const ackNeeded = messages.length > 0 && ackSeq > 0 && ownsCursor && (contigAdvanced || hasServerCursor && ackSeq > serverAckSeq);
+      if (ackNeeded) {
         this._safeAsync(this._ackGroupV2(gid, ackSeq).then(() => void 0));
       }
       const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
+      if (!ownsCursor) break;
       if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false) break;
       nextAfterSeq = nextAfter;
     }
@@ -14862,6 +14945,28 @@ var _AUNClient = class _AUNClient {
     }
     return decrypted;
   }
+  _groupCursorParams(params) {
+    const cursorParams = {};
+    for (const key of ["device_id", "slot_id", "device_name", "device_type"]) {
+      const value = params[key];
+      if (value !== void 0 && value !== null) cursorParams[key] = value;
+    }
+    return cursorParams;
+  }
+  _explicitGroupCursorParams(params) {
+    const value = params._group_cursor_params;
+    if (!isJsonObject(value)) return {};
+    return { ...value };
+  }
+  _groupCursorTargetsCurrentInstance(params) {
+    const deviceId = String(params.device_id ?? "").trim();
+    const slotId = String(params.slot_id ?? "").trim();
+    return (!deviceId || deviceId === (this._deviceId ?? "")) && (!slotId || slotId === (this._slotId ?? ""));
+  }
+  async _rawGroupAckMessages(params) {
+    const p = { ...params };
+    return await this._callRawV2Rpc("group.ack_messages", p);
+  }
   /**
    * 确认 V2 群消息已消费。
    *
@@ -14879,7 +14984,7 @@ var _AUNClient = class _AUNClient {
       this._clientLog.warn(`ackGroupV2 clamp: group=${gid} up_to_seq=${seq} > max_seen=${maxSeen}, clamp`);
       seq = maxSeen;
     }
-    return this.call("group.v2.ack", { group_id: gid, up_to_seq: seq });
+    return this._callRawV2Rpc("group.v2.ack", { group_id: gid, up_to_seq: seq });
   }
   // ── V2 thought（per-device wrap，服务端透传，不持久化）──────────
   /**
@@ -15638,8 +15743,8 @@ var _AUNClient = class _AUNClient {
         return;
       }
       let signature = "";
-      const identity = this._identity;
-      if (identity?.private_key_pem) {
+      const currentAid = this._currentAid;
+      if (currentAid?.privateKeyPem) {
         try {
           const signPayloadObj = {
             group_id: groupId,
@@ -15649,7 +15754,7 @@ var _AUNClient = class _AUNClient {
           };
           const signPayload = stableStringify(signPayloadObj);
           const signPayloadBytes = new TextEncoder().encode(signPayload);
-          const privKey = await importPrivateKeyEcdsa(identity.private_key_pem);
+          const privKey = await importPrivateKeyEcdsa(currentAid.privateKeyPem);
           const sigBytes = await ecdsaSignDer(privKey, signPayloadBytes);
           signature = uint8ToBase64(sigBytes);
         } catch (sigExc) {
@@ -15823,7 +15928,7 @@ var _AUNClient = class _AUNClient {
           if (newContig > 0 && newContig !== contigBefore) {
             const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
             const ackSeq = maxSeen > 0 ? Math.min(newContig, maxSeen) : newContig;
-            this.call("message.v2.ack", { up_to_seq: ackSeq }).catch((e) => this._clientLog.debug(`V2 P2P push-ack failed: ${e}`));
+            this._callRawV2Rpc("message.v2.ack", { up_to_seq: ackSeq }).catch((e) => this._clientLog.debug(`V2 P2P push-ack failed: ${e}`));
           }
           this._clientLog.debug(
             `_onV2PushNotification: push \u5E26 payload \u89E3\u5BC6\u6210\u529F, contiguous_seq=${contigBefore}->${newContig} push_seq=${pushSeq}`
@@ -16153,10 +16258,6 @@ function parseCertCN(certPem) {
     return null;
   }
 }
-function normalizeSlotId(slotId) {
-  const value = String(slotId ?? "default").trim();
-  return value || "default";
-}
 function issuerFromAid(aid) {
   const target = String(aid ?? "").trim();
   const dotIdx = target.indexOf(".");
@@ -16219,7 +16320,10 @@ var AIDStore = class {
     this._encryptionSeed = String(opts.encryptionSeed ?? "");
     this.deviceId = opts.deviceId ? normalizeInstanceId(opts.deviceId, "deviceId", { allowEmpty: true }) : getDeviceId();
     this.slotId = normalizeSlotId(opts.slotId);
-    this._verifySsl = opts.verifySsl ?? true;
+    if (opts.verifySsl === false) {
+      console.warn("[aun_core.config] verify_ssl=false \u5728\u6D4F\u89C8\u5668\u73AF\u5883\u4E2D\u4E0D\u53D7\u652F\u6301\uFF0CSSL \u8BC1\u4E66\u9A8C\u8BC1\u5C06\u4FDD\u6301\u542F\u7528\u3002");
+    }
+    this._verifySsl = opts.verifySsl === false ? true : opts.verifySsl ?? true;
     this._keystore = new IndexedDBKeyStore({ encryptionSeed: this._encryptionSeed || void 0 });
     this._crypto = new CryptoProvider();
     this._discovery = new GatewayDiscovery();