acp-ts 1.1.8 → 1.2.0

package/dist/agentcp.d.ts

@@ -1,7 +1,7 @@
 import { IAgentCP, IAgentIdentity } from "./interfaces";
 import { MessageStore } from "./messagestore";
 import { AgentMdOptions } from "./agentmd";
-import { ACPGroupClient, GroupOperations, ACPGroupEventHandler, CursorStore, GroupMessageStore, GroupMessage, MsgCursor } from "./group";
+import { ACPGroupClient, GroupOperations, ACPGroupEventHandler, CursorStore, GroupMessageStore, GroupMessage, GroupMessageBatch } from "./group";
 declare class AgentCP implements IAgentCP {
     private seedPassword;
     private apUrl;
@@ -90,15 +90,20 @@ declare class AgentCP implements IAgentCP {
     setGroupEventHandler(handler: ACPGroupEventHandler): void;
     /**
      * 创建默认的群组事件处理器。
-     * - onGroupMessage: 自动存储消息到 GroupMessageStore + 自动 ACK
+     * - onGroupMessageBatch: 自动存储消息 + watermark ACK
      * - onJoinApproved: 自动注册到 Home AP + 存储群组
      * 外部可通过 setGroupEventHandler 覆盖。
      */
     private _createDefaultGroupEventHandler;
     /**
-     * 自动 ACK 消息（SDK 内部行为，对上层透明）
+     * 处理批量推送消息：排序、存储、ACK 最后一条。
+     * 返回排序后的消息列表，供上层使用（如推送给浏览器）。
      */
-    private _autoAckMessage;
+    processAndAckBatch(groupId: string, batch: GroupMessageBatch): GroupMessage[];
+    /**
+     * 异步 ACK 消息（不阻塞调用方）
+     */
+    private _ackMessage;
     /**
      * 设置群组游标存储
      */
@@ -142,10 +147,6 @@ declare class AgentCP implements IAgentCP {
      * 添加群组到本地存储
      */
     addGroupToStore(groupId: string, name: string): void;
-    /**
-     * 将加入的群组注册到 Home AP（内部方法）
-     */
-    registerGroupToHomeAP(groupId: string, groupUrl: string, role?: string): Promise<void>;
     /**
      * 从本地存储删除群组
      */
@@ -178,18 +179,15 @@ declare class AgentCP implements IAgentCP {
     pullAndStoreGroupMessages(groupId: string, afterMsgId?: number, limit?: number): Promise<GroupMessage[]>;
     /**
      * 加入群组会话（完整生命周期）：
-     * 1. register_online → 获取游标状态
-     * 2. 如果有未读消息 → 循环 pull_messages + ACK
+     * 1. register_online → 告知 group.ap 在线
+     * 2. 将群组加入在线列表
      * 3. 启动心跳定时器（首次时启动）
-     *
-     * @returns msg_cursor 游标状态
      */
-    joinGroupSession(groupId: string): Promise<MsgCursor>;
+    joinGroupSession(groupId: string): Promise<void>;
     /**
      * 离开群组会话（优雅退出）：
-     * 1. unregister_online
-     * 2. 从在线群组列表移除
-     * 3. 如果没有在线群组了，停止心跳定时器
+     * 1. 从在线群组列表移除
+     * 2. 如果没有在线群组了，unregister_online + 停止心跳定时器
      */
     leaveGroupSession(groupId: string): Promise<void>;
     /**
@@ -213,7 +211,7 @@ declare class AgentCP implements IAgentCP {
      */
     private _stopHeartbeat;
     /**
-     * 对所有在线群组发送心跳
+     * 发送心跳保活
      */
     private _sendHeartbeats;
     /**

package/dist/agentcp.js

@@ -61,7 +61,7 @@ class AgentCP {
         this.groupMessageStore = null;
         this._groupTargetAid = '';
         this._groupSessionId = '';
-        this._persistGroupMessages = false;
+        this._persistGroupMessages = true;
         // Group lifecycle management
         this._onlineGroups = new Set();
         this._heartbeatTimer = null;
@@ -80,7 +80,7 @@ class AgentCP {
         this._basePath = basePath || process.cwd();
         this.apUrl = `${baseUrl}/api/accesspoint`;
         this.msgUrl = `${baseUrl}/api/message`;
-        this._persistGroupMessages = (_a = options === null || options === void 0 ? void 0 : options.persistGroupMessages) !== null && _a !== void 0 ? _a : false;
+        this._persistGroupMessages = (_a = options === null || options === void 0 ? void 0 : options.persistGroupMessages) !== null && _a !== void 0 ? _a : true;
         this._messageStore = new messagestore_1.MessageStore({
             persistMessages: (_b = options === null || options === void 0 ? void 0 : options.persistMessages) !== null && _b !== void 0 ? _b : false,
             basePath: this._basePath,
@@ -401,7 +401,7 @@ class AgentCP {
     }
     /**
      * 创建默认的群组事件处理器。
-     * - onGroupMessage: 自动存储消息到 GroupMessageStore + 自动 ACK
+     * - onGroupMessageBatch: 自动存储消息 + watermark ACK
      * - onJoinApproved: 自动注册到 Home AP + 存储群组
      * 外部可通过 setGroupEventHandler 覆盖。
      */
@@ -431,8 +431,6 @@ class AgentCP {
                         }
                         catch (_) { }
                         this.addGroupToStore(groupId, groupName);
-                        const groupUrl = groupAddress || `https://${this._groupTargetAid}/${groupId}`;
-                        await this.registerGroupToHomeAP(groupId, groupUrl);
                     }
                     catch (e) {
                         console.error(`[Group][DefaultHandler] onJoinApproved processing failed: group=${groupId}`, e.message);
@@ -445,12 +443,9 @@ class AgentCP {
             onJoinRequestReceived(groupId, agentId, message) {
                 console.log(`[Group][DefaultHandler] onJoinRequestReceived: group=${groupId} agent=${agentId}`);
             },
-            onGroupMessage: (groupId, msg) => {
-                console.log(`[Group][DefaultHandler] onGroupMessage: group=${groupId} msgId=${msg.msg_id} sender=${msg.sender}`);
-                // 自动存储消息到本地
-                this.addGroupMessageToStore(groupId, msg);
-                // 自动 ACK（异步，不阻塞回调）
-                this._autoAckMessage(groupId, msg.msg_id);
+            onGroupMessageBatch: (groupId, batch) => {
+                console.log(`[Group][DefaultHandler] onGroupMessageBatch: group=${groupId} count=${batch.count} range=[${batch.start_msg_id}, ${batch.latest_msg_id}]`);
+                this.processAndAckBatch(groupId, batch);
             },
             onGroupEvent(groupId, evt) {
                 console.log(`[Group][DefaultHandler] onGroupEvent: group=${groupId} event=${evt.event_type}`);
@@ -458,13 +453,27 @@ class AgentCP {
         };
     }
     /**
-     * 自动 ACK 消息（SDK 内部行为，对上层透明）
+     * 处理批量推送消息：排序、存储、ACK 最后一条。
+     * 返回排序后的消息列表，供上层使用（如推送给浏览器）。
      */
-    _autoAckMessage(groupId, msgId) {
+    processAndAckBatch(groupId, batch) {
+        const sorted = [...batch.messages].sort((a, b) => a.msg_id - b.msg_id);
+        this.addGroupMessagesToStore(groupId, sorted);
+        // ACK batch 中最后一条消息
+        if (sorted.length > 0) {
+            const lastMsgId = sorted[sorted.length - 1].msg_id;
+            this._ackMessage(groupId, lastMsgId);
+        }
+        return sorted;
+    }
+    /**
+     * 异步 ACK 消息（不阻塞调用方）
+     */
+    _ackMessage(groupId, msgId) {
         if (!this.groupOps || !this._groupTargetAid)
             return;
         this.groupOps.ackMessages(this._groupTargetAid, groupId, msgId).catch(e => {
-            console.warn(`[Group] auto ack failed: group=${groupId} msgId=${msgId}`, e.message || e);
+            console.warn(`[Group] ack failed: group=${groupId} msgId=${msgId}`, e.message || e);
         });
     }
     /**
@@ -574,20 +583,6 @@ class AgentCP {
             return;
         this.groupMessageStore.getOrCreateGroup(groupId, this._groupTargetAid, name);
     }
-    /**
-     * 将加入的群组注册到 Home AP（内部方法）
-     */
-    async registerGroupToHomeAP(groupId, groupUrl, role = 'member') {
-        if (!this.groupOps || !this._groupTargetAid)
-            return;
-        try {
-            await this.groupOps.registerMembership(this._groupTargetAid, groupId, groupUrl, this._groupTargetAid, this._groupSessionId, role);
-            console.log(`[Group] registerGroupToHomeAP success: group=${groupId}`);
-        }
-        catch (e) {
-            console.error(`[Group] registerGroupToHomeAP failed: group=${groupId}`, e.message);
-        }
-    }
     /**
      * 从本地存储删除群组
      */
@@ -685,47 +680,46 @@ class AgentCP {
     // ============================================================
     /**
      * 加入群组会话（完整生命周期）：
-     * 1. register_online → 获取游标状态
-     * 2. 如果有未读消息 → 循环 pull_messages + ACK
+     * 1. register_online → 告知 group.ap 在线
+     * 2. 将群组加入在线列表
      * 3. 启动心跳定时器（首次时启动）
-     *
-     * @returns msg_cursor 游标状态
      */
     async joinGroupSession(groupId) {
         if (!this.groupOps || !this._groupTargetAid) {
             throw new Error('群组客户端未初始化，请先调用 initGroupClient');
         }
-        // Step 1: register_online
-        const result = await this.groupOps.registerOnline(this._groupTargetAid, groupId);
-        const cursor = result.msg_cursor;
+        // Step 1: register_online（仅通知 group.ap 在线，不再返回游标）
+        await this.groupOps.registerOnline(this._groupTargetAid);
         this._onlineGroups.add(groupId);
-        console.log(`[Group] joinGroupSession: group=${groupId} unread=${cursor.unread_count} current=${cursor.current_msg_id} latest=${cursor.latest_msg_id}`);
-        // Step 2: 如果有未读消息，使用自动游标模式拉取
-        if (cursor.unread_count > 0) {
-            await this.pullAndStoreGroupMessages(groupId, 0, 0);
+        console.log(`[Group] joinGroupSession: group=${groupId}`);
+        // Step 2: 冷启动同步 — 拉取历史消息对齐，再进入批推送接收
+        try {
+            const lastMsgId = this.getGroupLastMsgId(groupId);
+            await this.pullAndStoreGroupMessages(groupId, lastMsgId, 50);
+        }
+        catch (e) {
+            console.warn(`[Group] cold-start sync failed: group=${groupId}`, e.message || e);
         }
         // Step 3: 启动心跳定时器（首次加入群组时启动）
         this._ensureHeartbeat();
-        return cursor;
     }
     /**
      * 离开群组会话（优雅退出）：
-     * 1. unregister_online
-     * 2. 从在线群组列表移除
-     * 3. 如果没有在线群组了，停止心跳定时器
+     * 1. 从在线群组列表移除
+     * 2. 如果没有在线群组了，unregister_online + 停止心跳定时器
      */
     async leaveGroupSession(groupId) {
         if (!this.groupOps || !this._groupTargetAid)
             return;
-        try {
-            await this.groupOps.unregisterOnline(this._groupTargetAid, groupId);
-        }
-        catch (e) {
-            console.warn(`[Group] unregisterOnline failed: group=${groupId}`, e.message || e);
-        }
         this._onlineGroups.delete(groupId);
-        // 如果没有在线群组了，停止心跳
+        // 如果没有在线群组了，通知 group.ap 下线并停止心跳
         if (this._onlineGroups.size === 0) {
+            try {
+                await this.groupOps.unregisterOnline(this._groupTargetAid);
+            }
+            catch (e) {
+                console.warn(`[Group] unregisterOnline failed`, e.message || e);
+            }
             this._stopHeartbeat();
         }
     }
@@ -779,16 +773,14 @@ class AgentCP {
         }
     }
     /**
-     * 对所有在线群组发送心跳
+     * 发送心跳保活
      */
     _sendHeartbeats() {
         if (!this.groupOps || !this._groupTargetAid)
             return;
-        for (const groupId of this._onlineGroups) {
-            this.groupOps.heartbeat(this._groupTargetAid, groupId).catch(e => {
-                console.warn(`[Group] heartbeat failed: group=${groupId}`, e.message || e);
-            });
-        }
+        this.groupOps.heartbeat(this._groupTargetAid).catch(e => {
+            console.warn(`[Group] heartbeat failed`, e.message || e);
+        });
     }
     /**
      * 关闭群消息存储，刷新所有未写入的数据

package/dist/group/client.js

@@ -74,7 +74,7 @@ class ACPGroupClient {
      * Called by the message dispatch chain in AgentCP.
      */
     handleIncoming(payload) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         let data;
         try {
             data = JSON.parse(payload);
@@ -116,31 +116,33 @@ class ACPGroupClient {
             }
             return;
         }
-        // Handle action-based push messages from group.ap (e.g. message_push)
-        // These have action field but no event/request_id, need to be mapped to notification events
+        // Handle batch push from group.ap
         const action = (_d = data.action) !== null && _d !== void 0 ? _d : "";
-        if (action === "message_push" && data.data) {
-            console.log(`[GroupClient] message_push -> group_message: group=${data.group_id} msg_id=${data.data.msg_id}`);
-            const msgData = data.data;
-            const notify = {
-                action: "group_notify",
-                group_id: (_e = data.group_id) !== null && _e !== void 0 ? _e : "",
-                event: types_1.NOTIFY_GROUP_MESSAGE,
-                data: {
-                    msg_id: (_f = msgData.msg_id) !== null && _f !== void 0 ? _f : 0,
-                    sender: (_g = msgData.sender) !== null && _g !== void 0 ? _g : "",
-                    content: (_h = msgData.content) !== null && _h !== void 0 ? _h : "",
-                    content_type: (_j = msgData.content_type) !== null && _j !== void 0 ? _j : "text",
-                    timestamp: (_k = msgData.timestamp) !== null && _k !== void 0 ? _k : 0,
-                    metadata: (_l = msgData.metadata) !== null && _l !== void 0 ? _l : null,
-                },
-                timestamp: (_m = msgData.timestamp) !== null && _m !== void 0 ? _m : 0,
+        if (action === types_1.ACTION_MESSAGE_BATCH_PUSH && data.data) {
+            const batchData = data.data;
+            const batch = {
+                messages: ((_e = batchData.messages) !== null && _e !== void 0 ? _e : []).map((m) => {
+                    var _a, _b, _c, _d, _e, _f;
+                    return ({
+                        msg_id: (_a = m.msg_id) !== null && _a !== void 0 ? _a : 0,
+                        sender: (_b = m.sender) !== null && _b !== void 0 ? _b : "",
+                        content: (_c = m.content) !== null && _c !== void 0 ? _c : "",
+                        content_type: (_d = m.content_type) !== null && _d !== void 0 ? _d : "text/plain",
+                        timestamp: (_e = m.timestamp) !== null && _e !== void 0 ? _e : 0,
+                        metadata: (_f = m.metadata) !== null && _f !== void 0 ? _f : null,
+                    });
+                }),
+                start_msg_id: (_f = batchData.start_msg_id) !== null && _f !== void 0 ? _f : 0,
+                latest_msg_id: (_g = batchData.latest_msg_id) !== null && _g !== void 0 ? _g : 0,
+                count: (_h = batchData.count) !== null && _h !== void 0 ? _h : 0,
             };
+            const groupId = (_j = data.group_id) !== null && _j !== void 0 ? _j : "";
+            console.log(`[GroupClient] message_batch_push: group=${groupId} count=${batch.count} range=[${batch.start_msg_id}, ${batch.latest_msg_id}]`);
             if (this._handler != null) {
-                (0, events_1.dispatchAcpNotify)(this._handler, notify);
+                this._handler.onGroupMessageBatch(groupId, batch);
             }
             else {
-                console.warn(`[GroupClient] !!! message_push dropped: no event handler registered.`);
+                console.warn(`[GroupClient] !!! message_batch_push dropped: no event handler registered.`);
             }
             return;
         }

package/dist/group/events.d.ts

@@ -2,7 +2,7 @@
  * Group event handler interfaces and dispatch logic.
  * Mirrors Python SDK: agentcp/group/events.py
  */
-import { GroupNotify, GroupMessage, GroupEvent } from './types';
+import { GroupNotify, GroupEvent, GroupMessageBatch } from './types';
 /**
  * Abstract handler for ACP group notifications.
  */
@@ -13,7 +13,7 @@ export interface ACPGroupEventHandler {
     onJoinApproved(groupId: string, groupAddress: string): void;
     onJoinRejected(groupId: string, reason: string): void;
     onJoinRequestReceived(groupId: string, agentId: string, message: string): void;
-    onGroupMessage(groupId: string, msg: GroupMessage): void;
+    onGroupMessageBatch(groupId: string, batch: GroupMessageBatch): void;
     onGroupEvent(groupId: string, evt: GroupEvent): void;
 }
 /**

package/dist/group/events.js

@@ -38,9 +38,6 @@ function dispatchAcpNotify(handler, notify) {
         else if (event === types_1.NOTIFY_JOIN_REQUEST_RECEIVED) {
             handler.onJoinRequestReceived(gid, (_l = data.agent_id) !== null && _l !== void 0 ? _l : "", (_m = data.message) !== null && _m !== void 0 ? _m : "");
         }
-        else if (event === types_1.NOTIFY_GROUP_MESSAGE) {
-            handler.onGroupMessage(gid, data);
-        }
         else if (event === types_1.NOTIFY_GROUP_EVENT) {
             handler.onGroupEvent(gid, data);
         }

package/dist/group/index.d.ts

@@ -2,7 +2,7 @@
  * ACP Group Operations package.
  * Mirrors Python SDK: agentcp/group/__init__.py
  */
-export { GroupErrorCode, GroupError, GroupRequest, GroupResponse, GroupNotify, buildGroupRequest, groupRequestToJson, parseGroupResponse, parseGroupNotify, GroupMessage, GroupEvent, MsgCursor, EventCursor, CursorState, createMsgCursor, createEventCursor, RegisterOnlineResp, CreateGroupResp, SendMessageResp, PullMessagesResp, PullEventsResp, GroupInfoResp, BanlistResp, BatchReviewResp, PendingRequestsResp, MembersResp, AdminsResp, RulesResp, AnnouncementResp, JoinRequirementsResp, MasterResp, InviteCodeResp, InviteCodeListResp, BroadcastLockResp, BroadcastPermissionResp, SyncStatusResp, SyncLogResp, ChecksumResp, PublicGroupInfoResp, SearchGroupsResp, DigestResp, MembershipInfo, ListMyGroupsResp, GetFileResp, GetSummaryResp, GetMetricsResp, NOTIFY_NEW_MESSAGE, NOTIFY_NEW_EVENT, NOTIFY_GROUP_INVITE, NOTIFY_JOIN_APPROVED, NOTIFY_JOIN_REJECTED, NOTIFY_JOIN_REQUEST_RECEIVED, NOTIFY_GROUP_MESSAGE, NOTIFY_GROUP_EVENT, EVENT_MEMBER_JOINED, EVENT_MEMBER_REMOVED, EVENT_MEMBER_LEFT, EVENT_MEMBER_BANNED, EVENT_META_UPDATED, EVENT_RULES_UPDATED, EVENT_ANNOUNCEMENT_UPDATED, EVENT_GROUP_DISSOLVED, EVENT_MASTER_TRANSFERRED, EVENT_GROUP_SUSPENDED, EVENT_GROUP_RESUMED, EVENT_MEMBER_UNBANNED, EVENT_JOIN_REQUIREMENTS_UPDATED, EVENT_INVITE_CODE_CREATED, EVENT_INVITE_CODE_REVOKED, } from './types';
+export { GroupErrorCode, GroupError, GroupRequest, GroupResponse, GroupNotify, buildGroupRequest, groupRequestToJson, parseGroupResponse, parseGroupNotify, GroupMessage, GroupEvent, MsgCursor, EventCursor, CursorState, createMsgCursor, createEventCursor, CreateGroupResp, SendMessageResp, PullMessagesResp, PullEventsResp, GroupInfoResp, BanlistResp, BatchReviewResp, PendingRequestsResp, MembersResp, AdminsResp, RulesResp, AnnouncementResp, JoinRequirementsResp, MasterResp, InviteCodeResp, InviteCodeListResp, BroadcastLockResp, BroadcastPermissionResp, SyncStatusResp, SyncLogResp, ChecksumResp, PublicGroupInfoResp, SearchGroupsResp, DigestResp, MembershipInfo, ListMyGroupsResp, GetFileResp, GetSummaryResp, GetMetricsResp, NOTIFY_NEW_MESSAGE, NOTIFY_NEW_EVENT, NOTIFY_GROUP_INVITE, NOTIFY_JOIN_APPROVED, NOTIFY_JOIN_REJECTED, NOTIFY_JOIN_REQUEST_RECEIVED, NOTIFY_GROUP_EVENT, EVENT_MEMBER_JOINED, EVENT_MEMBER_REMOVED, EVENT_MEMBER_LEFT, EVENT_MEMBER_BANNED, EVENT_META_UPDATED, EVENT_RULES_UPDATED, EVENT_ANNOUNCEMENT_UPDATED, EVENT_GROUP_DISSOLVED, EVENT_MASTER_TRANSFERRED, EVENT_GROUP_SUSPENDED, EVENT_GROUP_RESUMED, EVENT_MEMBER_UNBANNED, EVENT_JOIN_REQUIREMENTS_UPDATED, EVENT_INVITE_CODE_CREATED, EVENT_INVITE_CODE_REVOKED, ACTION_MESSAGE_BATCH_PUSH, GroupMessageBatch, } from './types';
 export { ACPGroupClient, SendFunc } from './client';
 export { GroupOperations, SyncHandler } from './operations';
 export { ACPGroupEventHandler, EventProcessor, dispatchAcpNotify, dispatchEvent, } from './events';

package/dist/group/index.js

@@ -4,7 +4,7 @@
  * Mirrors Python SDK: agentcp/group/__init__.py
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GroupMessageStore = exports.LocalCursorStore = exports.dispatchAcpNotify = exports.GroupOperations = exports.ACPGroupClient = exports.EVENT_INVITE_CODE_REVOKED = exports.EVENT_INVITE_CODE_CREATED = exports.EVENT_JOIN_REQUIREMENTS_UPDATED = exports.EVENT_MEMBER_UNBANNED = exports.EVENT_GROUP_RESUMED = exports.EVENT_GROUP_SUSPENDED = exports.EVENT_MASTER_TRANSFERRED = exports.EVENT_GROUP_DISSOLVED = exports.EVENT_ANNOUNCEMENT_UPDATED = exports.EVENT_RULES_UPDATED = exports.EVENT_META_UPDATED = exports.EVENT_MEMBER_BANNED = exports.EVENT_MEMBER_LEFT = exports.EVENT_MEMBER_REMOVED = exports.EVENT_MEMBER_JOINED = exports.NOTIFY_GROUP_EVENT = exports.NOTIFY_GROUP_MESSAGE = exports.NOTIFY_JOIN_REQUEST_RECEIVED = exports.NOTIFY_JOIN_REJECTED = exports.NOTIFY_JOIN_APPROVED = exports.NOTIFY_GROUP_INVITE = exports.NOTIFY_NEW_EVENT = exports.NOTIFY_NEW_MESSAGE = exports.createEventCursor = exports.createMsgCursor = exports.parseGroupNotify = exports.parseGroupResponse = exports.groupRequestToJson = exports.buildGroupRequest = exports.GroupError = exports.GroupErrorCode = void 0;
+exports.GroupMessageStore = exports.LocalCursorStore = exports.dispatchAcpNotify = exports.GroupOperations = exports.ACPGroupClient = exports.ACTION_MESSAGE_BATCH_PUSH = exports.EVENT_INVITE_CODE_REVOKED = exports.EVENT_INVITE_CODE_CREATED = exports.EVENT_JOIN_REQUIREMENTS_UPDATED = exports.EVENT_MEMBER_UNBANNED = exports.EVENT_GROUP_RESUMED = exports.EVENT_GROUP_SUSPENDED = exports.EVENT_MASTER_TRANSFERRED = exports.EVENT_GROUP_DISSOLVED = exports.EVENT_ANNOUNCEMENT_UPDATED = exports.EVENT_RULES_UPDATED = exports.EVENT_META_UPDATED = exports.EVENT_MEMBER_BANNED = exports.EVENT_MEMBER_LEFT = exports.EVENT_MEMBER_REMOVED = exports.EVENT_MEMBER_JOINED = exports.NOTIFY_GROUP_EVENT = exports.NOTIFY_JOIN_REQUEST_RECEIVED = exports.NOTIFY_JOIN_REJECTED = exports.NOTIFY_JOIN_APPROVED = exports.NOTIFY_GROUP_INVITE = exports.NOTIFY_NEW_EVENT = exports.NOTIFY_NEW_MESSAGE = exports.createEventCursor = exports.createMsgCursor = exports.parseGroupNotify = exports.parseGroupResponse = exports.groupRequestToJson = exports.buildGroupRequest = exports.GroupError = exports.GroupErrorCode = void 0;
 // Types
 var types_1 = require("./types");
 Object.defineProperty(exports, "GroupErrorCode", { enumerable: true, get: function () { return types_1.GroupErrorCode; } });
@@ -22,7 +22,6 @@ Object.defineProperty(exports, "NOTIFY_GROUP_INVITE", { enumerable: true, get: f
 Object.defineProperty(exports, "NOTIFY_JOIN_APPROVED", { enumerable: true, get: function () { return types_1.NOTIFY_JOIN_APPROVED; } });
 Object.defineProperty(exports, "NOTIFY_JOIN_REJECTED", { enumerable: true, get: function () { return types_1.NOTIFY_JOIN_REJECTED; } });
 Object.defineProperty(exports, "NOTIFY_JOIN_REQUEST_RECEIVED", { enumerable: true, get: function () { return types_1.NOTIFY_JOIN_REQUEST_RECEIVED; } });
-Object.defineProperty(exports, "NOTIFY_GROUP_MESSAGE", { enumerable: true, get: function () { return types_1.NOTIFY_GROUP_MESSAGE; } });
 Object.defineProperty(exports, "NOTIFY_GROUP_EVENT", { enumerable: true, get: function () { return types_1.NOTIFY_GROUP_EVENT; } });
 // Group event type constants
 Object.defineProperty(exports, "EVENT_MEMBER_JOINED", { enumerable: true, get: function () { return types_1.EVENT_MEMBER_JOINED; } });
@@ -40,6 +39,8 @@ Object.defineProperty(exports, "EVENT_MEMBER_UNBANNED", { enumerable: true, get:
 Object.defineProperty(exports, "EVENT_JOIN_REQUIREMENTS_UPDATED", { enumerable: true, get: function () { return types_1.EVENT_JOIN_REQUIREMENTS_UPDATED; } });
 Object.defineProperty(exports, "EVENT_INVITE_CODE_CREATED", { enumerable: true, get: function () { return types_1.EVENT_INVITE_CODE_CREATED; } });
 Object.defineProperty(exports, "EVENT_INVITE_CODE_REVOKED", { enumerable: true, get: function () { return types_1.EVENT_INVITE_CODE_REVOKED; } });
+// Batch push
+Object.defineProperty(exports, "ACTION_MESSAGE_BATCH_PUSH", { enumerable: true, get: function () { return types_1.ACTION_MESSAGE_BATCH_PUSH; } });
 // Client
 var client_1 = require("./client");
 Object.defineProperty(exports, "ACPGroupClient", { enumerable: true, get: function () { return client_1.ACPGroupClient; } });

package/dist/group/operations.d.ts

@@ -3,7 +3,7 @@
  * Mirrors Python SDK: agentcp/group/operations.py
  */
 import { ACPGroupClient } from './client';
-import { RegisterOnlineResp, CreateGroupResp, SendMessageResp, PullMessagesResp, PullEventsResp, CursorState, GroupInfoResp, BanlistResp, BatchReviewResp, PendingRequestsResp, MembersResp, AdminsResp, RulesResp, AnnouncementResp, JoinRequirementsResp, MasterResp, InviteCodeResp, InviteCodeListResp, BroadcastLockResp, BroadcastPermissionResp, SyncStatusResp, SyncLogResp, ChecksumResp, PublicGroupInfoResp, SearchGroupsResp, DigestResp, ListMyGroupsResp, GetFileResp, GetSummaryResp, GetMetricsResp } from './types';
+import { CreateGroupResp, SendMessageResp, PullMessagesResp, PullEventsResp, CursorState, GroupInfoResp, BanlistResp, BatchReviewResp, PendingRequestsResp, MembersResp, AdminsResp, RulesResp, AnnouncementResp, JoinRequirementsResp, MasterResp, InviteCodeResp, InviteCodeListResp, BroadcastLockResp, BroadcastPermissionResp, SyncStatusResp, SyncLogResp, ChecksumResp, PublicGroupInfoResp, SearchGroupsResp, DigestResp, ListMyGroupsResp, GetFileResp, GetSummaryResp, GetMetricsResp } from './types';
 /**
  * Callback interface for syncGroup.
  */
@@ -43,20 +43,20 @@ export declare class GroupOperations {
         message?: string;
     }): Promise<string>;
     /**
-     * 注册上线，获取游标状态。
-     * 客户端每次启动或重新连接时，必须对每个群组调用。
+     * 注册上线，告知 group.ap 当前客户端在线，可以接收消息推送。
+     * 客户端每次启动或重新连接时调用一次即可。
      */
-    registerOnline(targetAid: string, groupId: string): Promise<RegisterOnlineResp>;
+    registerOnline(targetAid: string): Promise<void>;
     /**
      * 主动下线（优雅退出）。
      * 客户端退出时调用，立即从在线列表移除。
      */
-    unregisterOnline(targetAid: string, groupId: string): Promise<void>;
+    unregisterOnline(targetAid: string): Promise<void>;
     /**
      * 心跳保活。
      * 在线注册有 5 分钟超时，SDK 需定时发送（建议 2~4 分钟）。
      */
-    heartbeat(targetAid: string, groupId: string): Promise<void>;
+    heartbeat(targetAid: string): Promise<void>;
     createGroup(targetAid: string, name: string, options?: {
         alias?: string;
         subject?: string;
@@ -126,7 +126,6 @@ export declare class GroupOperations {
     }): Promise<SearchGroupsResp>;
     generateDigest(targetAid: string, groupId: string, date: string, period: string): Promise<DigestResp>;
     getDigest(targetAid: string, groupId: string, date: string, period: string): Promise<DigestResp>;
-    registerMembership(targetAid: string, groupId: string, groupUrl: string, groupServer: string, sessionId: string, role: string): Promise<void>;
     listMyGroups(targetAid: string, status?: number): Promise<ListMyGroupsResp>;
     unregisterMembership(targetAid: string, groupId: string): Promise<void>;
     changeMemberRole(targetAid: string, groupId: string, agentId: string, newRole: string): Promise<void>;

package/dist/group/operations.js

@@ -62,31 +62,27 @@ class GroupOperations {
     // Phase 0: Lifecycle (register / heartbeat / unregister)
     // ============================================================
     /**
-     * 注册上线，获取游标状态。
-     * 客户端每次启动或重新连接时，必须对每个群组调用。
+     * 注册上线，告知 group.ap 当前客户端在线，可以接收消息推送。
+     * 客户端每次启动或重新连接时调用一次即可。
      */
-    async registerOnline(targetAid, groupId) {
-        const resp = await this._client.sendRequest(targetAid, groupId, "register_online", null);
+    async registerOnline(targetAid) {
+        const resp = await this._client.sendRequest(targetAid, "", "register_online", null);
         this._check(resp, "register_online");
-        const d = resp.data || {};
-        return {
-            msg_cursor: (0, types_1.createMsgCursor)(d.msg_cursor),
-        };
     }
     /**
      * 主动下线（优雅退出）。
      * 客户端退出时调用，立即从在线列表移除。
      */
-    async unregisterOnline(targetAid, groupId) {
-        const resp = await this._client.sendRequest(targetAid, groupId, "unregister_online", null);
+    async unregisterOnline(targetAid) {
+        const resp = await this._client.sendRequest(targetAid, "", "unregister_online", null);
         this._check(resp, "unregister_online");
     }
     /**
      * 心跳保活。
      * 在线注册有 5 分钟超时，SDK 需定时发送（建议 2~4 分钟）。
      */
-    async heartbeat(targetAid, groupId) {
-        const resp = await this._client.sendRequest(targetAid, groupId, "heartbeat", null);
+    async heartbeat(targetAid) {
+        const resp = await this._client.sendRequest(targetAid, "", "heartbeat", null);
         this._check(resp, "heartbeat");
     }
     // ============================================================
@@ -562,14 +558,6 @@ class GroupOperations {
     // ============================================================
     // Phase 5: Home AP Membership Index
     // ============================================================
-    async registerMembership(targetAid, groupId, groupUrl, groupServer, sessionId, role) {
-        const params = {
-            group_id: groupId, group_url: groupUrl,
-            group_server: groupServer, session_id: sessionId, role,
-        };
-        const resp = await this._client.sendRequest(targetAid, groupId, "register_membership", params);
-        this._check(resp, "register_membership");
-    }
     async listMyGroups(targetAid, status = 0) {
         var _a, _b;
         const params = {};

package/dist/group/types.d.ts

@@ -85,9 +85,6 @@ export interface CursorState {
     msg_cursor: MsgCursor;
     event_cursor: EventCursor;
 }
-export interface RegisterOnlineResp {
-    msg_cursor: MsgCursor;
-}
 export interface CreateGroupResp {
     group_id: string;
     group_url: string;
@@ -250,7 +247,6 @@ export declare const NOTIFY_GROUP_INVITE = "group_invite";
 export declare const NOTIFY_JOIN_APPROVED = "join_approved";
 export declare const NOTIFY_JOIN_REJECTED = "join_rejected";
 export declare const NOTIFY_JOIN_REQUEST_RECEIVED = "join_request_received";
-export declare const NOTIFY_GROUP_MESSAGE = "group_message";
 export declare const NOTIFY_GROUP_EVENT = "group_event";
 export declare const EVENT_MEMBER_JOINED = "member_joined";
 export declare const EVENT_MEMBER_REMOVED = "member_removed";
@@ -267,3 +263,10 @@ export declare const EVENT_MEMBER_UNBANNED = "member_unbanned";
 export declare const EVENT_JOIN_REQUIREMENTS_UPDATED = "join_requirements_updated";
 export declare const EVENT_INVITE_CODE_CREATED = "invite_code_created";
 export declare const EVENT_INVITE_CODE_REVOKED = "invite_code_revoked";
+export declare const ACTION_MESSAGE_BATCH_PUSH = "message_batch_push";
+export interface GroupMessageBatch {
+    messages: GroupMessage[];
+    start_msg_id: number;
+    latest_msg_id: number;
+    count: number;
+}

package/dist/group/types.js

@@ -4,7 +4,7 @@
  * Mirrors Python SDK: agentcp/group/types.py
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EVENT_INVITE_CODE_REVOKED = exports.EVENT_INVITE_CODE_CREATED = exports.EVENT_JOIN_REQUIREMENTS_UPDATED = exports.EVENT_MEMBER_UNBANNED = exports.EVENT_GROUP_RESUMED = exports.EVENT_GROUP_SUSPENDED = exports.EVENT_MASTER_TRANSFERRED = exports.EVENT_GROUP_DISSOLVED = exports.EVENT_ANNOUNCEMENT_UPDATED = exports.EVENT_RULES_UPDATED = exports.EVENT_META_UPDATED = exports.EVENT_MEMBER_BANNED = exports.EVENT_MEMBER_LEFT = exports.EVENT_MEMBER_REMOVED = exports.EVENT_MEMBER_JOINED = exports.NOTIFY_GROUP_EVENT = exports.NOTIFY_GROUP_MESSAGE = exports.NOTIFY_JOIN_REQUEST_RECEIVED = exports.NOTIFY_JOIN_REJECTED = exports.NOTIFY_JOIN_APPROVED = exports.NOTIFY_GROUP_INVITE = exports.NOTIFY_NEW_EVENT = exports.NOTIFY_NEW_MESSAGE = exports.GroupError = exports.GroupErrorCode = void 0;
+exports.ACTION_MESSAGE_BATCH_PUSH = exports.EVENT_INVITE_CODE_REVOKED = exports.EVENT_INVITE_CODE_CREATED = exports.EVENT_JOIN_REQUIREMENTS_UPDATED = exports.EVENT_MEMBER_UNBANNED = exports.EVENT_GROUP_RESUMED = exports.EVENT_GROUP_SUSPENDED = exports.EVENT_MASTER_TRANSFERRED = exports.EVENT_GROUP_DISSOLVED = exports.EVENT_ANNOUNCEMENT_UPDATED = exports.EVENT_RULES_UPDATED = exports.EVENT_META_UPDATED = exports.EVENT_MEMBER_BANNED = exports.EVENT_MEMBER_LEFT = exports.EVENT_MEMBER_REMOVED = exports.EVENT_MEMBER_JOINED = exports.NOTIFY_GROUP_EVENT = exports.NOTIFY_JOIN_REQUEST_RECEIVED = exports.NOTIFY_JOIN_REJECTED = exports.NOTIFY_JOIN_APPROVED = exports.NOTIFY_GROUP_INVITE = exports.NOTIFY_NEW_EVENT = exports.NOTIFY_NEW_MESSAGE = exports.GroupError = exports.GroupErrorCode = void 0;
 exports.buildGroupRequest = buildGroupRequest;
 exports.groupRequestToJson = groupRequestToJson;
 exports.parseGroupResponse = parseGroupResponse;
@@ -120,7 +120,6 @@ exports.NOTIFY_GROUP_INVITE = "group_invite";
 exports.NOTIFY_JOIN_APPROVED = "join_approved";
 exports.NOTIFY_JOIN_REJECTED = "join_rejected";
 exports.NOTIFY_JOIN_REQUEST_RECEIVED = "join_request_received";
-exports.NOTIFY_GROUP_MESSAGE = "group_message";
 exports.NOTIFY_GROUP_EVENT = "group_event";
 // Group Event Type Constants
 exports.EVENT_MEMBER_JOINED = "member_joined";
@@ -138,3 +137,7 @@ exports.EVENT_MEMBER_UNBANNED = "member_unbanned";
 exports.EVENT_JOIN_REQUIREMENTS_UPDATED = "join_requirements_updated";
 exports.EVENT_INVITE_CODE_CREATED = "invite_code_created";
 exports.EVENT_INVITE_CODE_REVOKED = "invite_code_revoked";
+// ============================================================
+// Batch Push Constants & Types
+// ============================================================
+exports.ACTION_MESSAGE_BATCH_PUSH = "message_batch_push";

package/dist/server.js

@@ -304,8 +304,6 @@ async function ensureGroupClient(instance) {
                     }
                     catch (_) { }
                     instance.agentCP.addGroupToStore(groupId, groupName);
-                    const groupUrl = groupAddress || `https://${instance.groupTargetAid}/${groupId}`;
-                    await instance.agentCP.registerGroupToHomeAP(groupId, groupUrl);
                     // 新加入的群也立即注册在线
                     await instance.agentCP.joinGroupSession(groupId);
                 }
@@ -327,19 +325,18 @@ async function ensureGroupClient(instance) {
             console.log(`[Group] onJoinRequestReceived: group=${groupId} agent=${agentId} msg=${message}`);
             broadcastToBrowser({ type: 'join_request', group_id: groupId, agent_id: agentId, message });
         },
-        onGroupMessage(groupId, msg) {
-            var _a;
-            console.log(`[Group] onGroupMessage: group=${groupId} msgId=${msg.msg_id} sender=${msg.sender}`);
-            // 存储消息到本地 + 自动 ACK
-            instance.agentCP.addGroupMessageToStore(groupId, msg);
-            (_a = instance.agentCP.groupOps) === null || _a === void 0 ? void 0 : _a.ackMessages(instance.groupTargetAid, groupId, msg.msg_id).catch(e => {
-                console.warn(`[Group] auto ack failed: group=${groupId} msgId=${msg.msg_id}`, e.message || e);
-            });
-            // 推送给浏览器
+        onGroupMessageBatch(groupId, batch) {
+            console.log(`[Group] onGroupMessageBatch: group=${groupId} count=${batch.count} range=[${batch.start_msg_id}, ${batch.latest_msg_id}]`);
+            // 存储 + ACK（统一由 agentcp 处理）
+            const sorted = instance.agentCP.processAndAckBatch(groupId, batch);
+            // 推送消息列表给浏览器
             broadcastToBrowser({
-                type: 'group_message',
+                type: 'group_message_batch',
                 group_id: groupId,
-                message: msg,
+                messages: sorted,
+                count: batch.count,
+                start_msg_id: batch.start_msg_id,
+                latest_msg_id: batch.latest_msg_id,
             });
         },
         onGroupEvent(groupId, evt) {
@@ -1667,6 +1664,24 @@ const chatHtml = `<!DOCTYPE html>
                         renderGroupMsgs(_lastGroupMsgs);
                     }
                 }
+            } else if(data.type==='group_message_batch'){
+                // 批量推送的消息列表
+                var gid=data.group_id;
+                var msgs=data.messages||[];
+                if(gid===S.activeGroupId&&S.tab==='group'){
+                    var changed=false;
+                    msgs.forEach(function(msg){
+                        var exists=_lastGroupMsgs.some(function(m){ return m.msg_id===msg.msg_id; });
+                        if(!exists){
+                            _lastGroupMsgs.push(msg);
+                            changed=true;
+                        }
+                    });
+                    if(changed){
+                        _lastGroupMsgSig=''; // 强制重新渲染
+                        renderGroupMsgs(_lastGroupMsgs);
+                    }
+                }
             } else if(data.type==='new_message_notify'){
                 // 轻量通知：如果是当前活跃群组，拉取最新消息（本地读取，很快）
                 if(data.group_id===S.activeGroupId&&S.tab==='group'){
@@ -2676,9 +2691,6 @@ async function handleRequest(req, res) {
                 }
                 catch (_) { }
                 instance.agentCP.addGroupToStore(groupId, groupName);
-                // 注册到 Home AP
-                const registrationUrl = `https://${targetAid}/${groupId}`;
-                await instance.agentCP.registerGroupToHomeAP(groupId, registrationUrl);
                 sendJson(res, { success: true, group_id: groupId });
             }
             else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acp-ts",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "基于 ACP智能体通信协议 的智能体通信库，提供智能体身份管理和实时通信功能",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",