@agentunion/fastaun-browser 0.4.3 → 0.4.4

package/dist/bundle.js

@@ -454,7 +454,7 @@ var init_indexeddb_store = __esm({
 });
 
 // src/version.ts
-var VERSION = "0.4.3";
+var VERSION = "0.4.4";
 
 // src/types.ts
 var ConnectionState = /* @__PURE__ */ ((ConnectionState2) => {
@@ -3142,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;
@@ -9703,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", "");
@@ -9721,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;
   }
@@ -9740,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);
     }
@@ -9758,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);
@@ -9809,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);
@@ -9941,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",
@@ -10358,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());
@@ -10433,10 +10458,10 @@ var _AUNClient = class _AUNClient {
      */
     __publicField(this, "_v2PullInflight", false);
     __publicField(this, "_v2PullPending", false);
-    const inputAid = aid !== null && aid !== void 0 && typeof aid.aunPath === "string" && typeof aid.isPrivateKeyValid === "function" ? 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 inputAid = aid ?? null;
     const rawConfig = {};
     if (inputAid) rawConfig.aun_path = inputAid.aunPath;
     const _debug = inputAid ? inputAid.debug : false;
@@ -10460,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 };
@@ -10489,7 +10514,7 @@ var _AUNClient = class _AUNClient {
         this._currentAid = inputAid;
         this._identity = {
           aid: inputAid.aid,
-          private_key_pem: inputAid._privateKeyPem ?? "",
+          private_key_pem: inputAid.privateKeyPem,
           public_key_der_b64: inputAid.publicKey,
           cert: inputAid.certPem
         };
@@ -11215,22 +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._slotId = aid.slotId || "default";
     this._state = "disconnected";
     this._closing = false;
   }
@@ -11274,9 +11355,6 @@ var _AUNClient = class _AUNClient {
   get gatewayUrl() {
     return this._gatewayUrl;
   }
-  set gatewayUrl(url) {
-    this._gatewayUrl = url;
-  }
   get discovery() {
     return this._discovery;
   }
@@ -11317,10 +11395,11 @@ var _AUNClient = class _AUNClient {
   /** 连接到 Gateway；身份来自构造函数或 loadIdentity(aid)，认证由 SDK 内部自动完成。 */
   async connect(opts) {
     const tStart = Date.now();
-    if (opts !== void 0 && typeof opts === "object") {
+    if (opts !== void 0 && opts !== null && typeof opts === "object") {
       const raw = opts;
-      if ("access_token" in raw || "aid" in raw || "token" in raw) {
-        throw new ValidationError("connect options must not include access_token/aid; these are managed internally");
+      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 ?? "";
@@ -11482,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);
@@ -11500,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,
@@ -11517,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,
@@ -11534,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);
       }
@@ -11545,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);
       }
@@ -11565,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
@@ -11685,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);
     }
@@ -12014,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));
+      }
     }
   }
   /** 后台补齐群事件空洞 */
@@ -12159,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 清理。 */
@@ -13039,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)) {
@@ -13057,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,
@@ -13072,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);
@@ -13172,12 +13227,20 @@ 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");
       }
-      if (this._sessionOptions?.background_sync !== false) {
+      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._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? "-"}`);
@@ -14056,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 公钥，
@@ -14065,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(
@@ -14461,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);
@@ -14476,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));
         }
       }
@@ -14505,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);
@@ -14775,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?)");
     }
@@ -14783,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);
@@ -14853,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);
@@ -14867,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;
     }
@@ -14879,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 群消息已消费。
    *
@@ -14896,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，服务端透传，不持久化）──────────
   /**
@@ -15655,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,
@@ -15666,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) {
@@ -15840,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}`