acp-ts 1.1.6 → 1.1.8

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 } from "./group";
+import { ACPGroupClient, GroupOperations, ACPGroupEventHandler, CursorStore, GroupMessageStore, GroupMessage, MsgCursor } from "./group";
 declare class AgentCP implements IAgentCP {
     private seedPassword;
     private apUrl;
@@ -19,6 +19,9 @@ declare class AgentCP implements IAgentCP {
     private _groupTargetAid;
     private _groupSessionId;
     private _persistGroupMessages;
+    private _onlineGroups;
+    private _heartbeatTimer;
+    private _heartbeatIntervalMs;
     get messageStore(): MessageStore;
     constructor(apiUrl: string, seedPassword?: string, basePath?: string, options?: {
         persistMessages?: boolean;
@@ -86,16 +89,23 @@ declare class AgentCP implements IAgentCP {
      */
     setGroupEventHandler(handler: ACPGroupEventHandler): void;
     /**
-     * 创建默认的群组事件处理器（防御性，仅打印日志）。
+     * 创建默认的群组事件处理器。
+     * - onGroupMessage: 自动存储消息到 GroupMessageStore + 自动 ACK
+     * - onJoinApproved: 自动注册到 Home AP + 存储群组
      * 外部可通过 setGroupEventHandler 覆盖。
      */
     private _createDefaultGroupEventHandler;
+    /**
+     * 自动 ACK 消息（SDK 内部行为，对上层透明）
+     */
+    private _autoAckMessage;
     /**
      * 设置群组游标存储
      */
     setGroupCursorStore(store: CursorStore): void;
     /**
-     * 关闭群组客户端
+     * 关闭群组客户端。
+     * 自动停止心跳、清理在线群组状态。
      */
     closeGroupClient(): void;
     /**
@@ -132,6 +142,10 @@ declare class AgentCP implements IAgentCP {
      * 添加群组到本地存储
      */
     addGroupToStore(groupId: string, name: string): void;
+    /**
+     * 将加入的群组注册到 Home AP（内部方法）
+     */
+    registerGroupToHomeAP(groupId: string, groupUrl: string, role?: string): Promise<void>;
     /**
      * 从本地存储删除群组
      */
@@ -154,9 +168,54 @@ declare class AgentCP implements IAgentCP {
     getGroupLastMsgId(groupId: string): number;
     /**
      * 从服务端拉取新消息并同步到本地存储。
+     * 循环拉取直到 has_more=false，每批拉取后自动 ACK。
      * 返回所有本地缓存的消息（包括新拉取的）。
+     *
+     * @param groupId 群组 ID
+     * @param afterMsgId 从哪条消息之后开始拉取，0 表示使用服务端自动游标模式
+     * @param limit 每次拉取数量上限，0 表示使用服务端默认值
+     */
+    pullAndStoreGroupMessages(groupId: string, afterMsgId?: number, limit?: number): Promise<GroupMessage[]>;
+    /**
+     * 加入群组会话（完整生命周期）：
+     * 1. register_online → 获取游标状态
+     * 2. 如果有未读消息 → 循环 pull_messages + ACK
+     * 3. 启动心跳定时器（首次时启动）
+     *
+     * @returns msg_cursor 游标状态
+     */
+    joinGroupSession(groupId: string): Promise<MsgCursor>;
+    /**
+     * 离开群组会话（优雅退出）：
+     * 1. unregister_online
+     * 2. 从在线群组列表移除
+     * 3. 如果没有在线群组了，停止心跳定时器
+     */
+    leaveGroupSession(groupId: string): Promise<void>;
+    /**
+     * 离开所有群组会话
+     */
+    leaveAllGroupSessions(): Promise<void>;
+    /**
+     * 获取当前在线群组列表
+     */
+    getOnlineGroups(): string[];
+    /**
+     * 设置心跳间隔（毫秒），默认 180000（3 分钟）
+     */
+    setHeartbeatInterval(intervalMs: number): void;
+    /**
+     * 确保心跳定时器已启动
+     */
+    private _ensureHeartbeat;
+    /**
+     * 停止心跳定时器
+     */
+    private _stopHeartbeat;
+    /**
+     * 对所有在线群组发送心跳
      */
-    pullAndStoreGroupMessages(groupId: string, limit?: number): Promise<GroupMessage[]>;
+    private _sendHeartbeats;
     /**
      * 关闭群消息存储，刷新所有未写入的数据
      */

package/dist/agentcp.js

@@ -62,6 +62,10 @@ class AgentCP {
         this._groupTargetAid = '';
         this._groupSessionId = '';
         this._persistGroupMessages = false;
+        // Group lifecycle management
+        this._onlineGroups = new Set();
+        this._heartbeatTimer = null;
+        this._heartbeatIntervalMs = 180000; // 3 minutes
         if (!apiUrl) {
             this.handleError("参数缺失：apiUrl不应为空");
         }
@@ -369,11 +373,9 @@ class AgentCP {
         }
         const data = message.data || message;
         const sender = (_a = data.sender) !== null && _a !== void 0 ? _a : "";
-        // console.log(`[Group] handleGroupMessage: sender="${sender}" targetAid="${this._groupTargetAid}" match=${sender === this._groupTargetAid}`);
         if (sender === this._groupTargetAid) {
             try {
                 const rawMsg = (_b = data.message) !== null && _b !== void 0 ? _b : "";
-                // console.log(`[Group] rawMsg type=${typeof rawMsg}, length=${typeof rawMsg === 'string' ? rawMsg.length : 'N/A'}, first 300 chars: ${typeof rawMsg === 'string' ? rawMsg.substring(0, 300) : JSON.stringify(rawMsg).substring(0, 300)}`);
                 if (typeof rawMsg === 'string' && rawMsg) {
                     this.groupClient.handleIncoming(rawMsg);
                 }
@@ -398,7 +400,9 @@ class AgentCP {
         }
     }
     /**
-     * 创建默认的群组事件处理器（防御性，仅打印日志）。
+     * 创建默认的群组事件处理器。
+     * - onGroupMessage: 自动存储消息到 GroupMessageStore + 自动 ACK
+     * - onJoinApproved: 自动注册到 Home AP + 存储群组
      * 外部可通过 setGroupEventHandler 覆盖。
      */
     _createDefaultGroupEventHandler() {
@@ -412,8 +416,28 @@ class AgentCP {
             onGroupInvite(groupId, groupAddress, invitedBy) {
                 console.log(`[Group][DefaultHandler] onGroupInvite: group=${groupId} address=${groupAddress} invitedBy=${invitedBy}`);
             },
-            onJoinApproved(groupId, groupAddress) {
+            onJoinApproved: (groupId, groupAddress) => {
                 console.log(`[Group][DefaultHandler] onJoinApproved: group=${groupId} address=${groupAddress}`);
+                (async () => {
+                    try {
+                        if (!this.groupOps || !this._groupTargetAid) {
+                            console.warn(`[Group][DefaultHandler] onJoinApproved skipped: groupOps or targetAid not available`);
+                            return;
+                        }
+                        let groupName = groupId;
+                        try {
+                            const info = await this.groupOps.getGroupInfo(this._groupTargetAid, groupId);
+                            groupName = info.name || groupId;
+                        }
+                        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);
+                    }
+                })();
             },
             onJoinRejected(groupId, reason) {
                 console.log(`[Group][DefaultHandler] onJoinRejected: group=${groupId} reason=${reason}`);
@@ -421,14 +445,28 @@ class AgentCP {
             onJoinRequestReceived(groupId, agentId, message) {
                 console.log(`[Group][DefaultHandler] onJoinRequestReceived: group=${groupId} agent=${agentId}`);
             },
-            onGroupMessage(groupId, msg) {
+            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);
             },
             onGroupEvent(groupId, evt) {
                 console.log(`[Group][DefaultHandler] onGroupEvent: group=${groupId} event=${evt.event_type}`);
             },
         };
     }
+    /**
+     * 自动 ACK 消息（SDK 内部行为，对上层透明）
+     */
+    _autoAckMessage(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);
+        });
+    }
     /**
      * 设置群组游标存储
      */
@@ -438,9 +476,12 @@ class AgentCP {
         }
     }
     /**
-     * 关闭群组客户端
+     * 关闭群组客户端。
+     * 自动停止心跳、清理在线群组状态。
      */
     closeGroupClient() {
+        this._stopHeartbeat();
+        this._onlineGroups.clear();
         if (this.groupClient) {
             try {
                 this.groupClient.close();
@@ -533,6 +574,20 @@ 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);
+        }
+    }
     /**
      * 从本地存储删除群组
      */
@@ -580,16 +635,24 @@ class AgentCP {
     }
     /**
      * 从服务端拉取新消息并同步到本地存储。
+     * 循环拉取直到 has_more=false，每批拉取后自动 ACK。
      * 返回所有本地缓存的消息（包括新拉取的）。
+     *
+     * @param groupId 群组 ID
+     * @param afterMsgId 从哪条消息之后开始拉取，0 表示使用服务端自动游标模式
+     * @param limit 每次拉取数量上限，0 表示使用服务端默认值
      */
-    async pullAndStoreGroupMessages(groupId, limit = 50) {
+    async pullAndStoreGroupMessages(groupId, afterMsgId = 0, limit = 50) {
         if (!this.groupOps || !this._groupTargetAid) {
             throw new Error('群组客户端未初始化');
         }
-        const lastMsgId = this.getGroupLastMsgId(groupId);
+        let after = afterMsgId;
         try {
-            const pulled = await this.groupOps.pullMessages(this._groupTargetAid, groupId, lastMsgId, limit);
-            if (pulled.messages && pulled.messages.length > 0) {
+            while (true) {
+                const pulled = await this.groupOps.pullMessages(this._groupTargetAid, groupId, after, limit);
+                if (!pulled.messages || pulled.messages.length === 0) {
+                    break;
+                }
                 const msgs = pulled.messages.map(m => {
                     var _a, _b, _c, _d, _e, _f;
                     return ({
@@ -602,13 +665,131 @@ class AgentCP {
                     });
                 });
                 this.addGroupMessagesToStore(groupId, msgs);
+                // ACK 这批消息中的最后一条
+                const lastMsgId = msgs[msgs.length - 1].msg_id;
+                await this.groupOps.ackMessages(this._groupTargetAid, groupId, lastMsgId);
+                // 更新 after 用于下一轮拉取
+                after = lastMsgId;
+                if (!pulled.has_more) {
+                    break;
+                }
             }
         }
         catch (e) {
-            console.warn('[AgentCP] pullMessages error:', e.message);
+            console.warn('[AgentCP] pullAndStoreGroupMessages error:', e.message);
         }
         return this.getLocalGroupMessages(groupId);
     }
+    // ============================================================
+    // Group Session Lifecycle (register_online / pull / heartbeat / unregister)
+    // ============================================================
+    /**
+     * 加入群组会话（完整生命周期）：
+     * 1. register_online → 获取游标状态
+     * 2. 如果有未读消息 → 循环 pull_messages + ACK
+     * 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;
+        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);
+        }
+        // Step 3: 启动心跳定时器（首次加入群组时启动）
+        this._ensureHeartbeat();
+        return cursor;
+    }
+    /**
+     * 离开群组会话（优雅退出）：
+     * 1. unregister_online
+     * 2. 从在线群组列表移除
+     * 3. 如果没有在线群组了，停止心跳定时器
+     */
+    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);
+        // 如果没有在线群组了，停止心跳
+        if (this._onlineGroups.size === 0) {
+            this._stopHeartbeat();
+        }
+    }
+    /**
+     * 离开所有群组会话
+     */
+    async leaveAllGroupSessions() {
+        const groups = Array.from(this._onlineGroups);
+        for (const groupId of groups) {
+            await this.leaveGroupSession(groupId);
+        }
+    }
+    /**
+     * 获取当前在线群组列表
+     */
+    getOnlineGroups() {
+        return Array.from(this._onlineGroups);
+    }
+    /**
+     * 设置心跳间隔（毫秒），默认 180000（3 分钟）
+     */
+    setHeartbeatInterval(intervalMs) {
+        this._heartbeatIntervalMs = intervalMs;
+        // 如果心跳已在运行，重新启动以应用新间隔
+        if (this._heartbeatTimer) {
+            this._stopHeartbeat();
+            this._ensureHeartbeat();
+        }
+    }
+    /**
+     * 确保心跳定时器已启动
+     */
+    _ensureHeartbeat() {
+        if (this._heartbeatTimer)
+            return;
+        if (this._onlineGroups.size === 0)
+            return;
+        this._heartbeatTimer = setInterval(() => {
+            this._sendHeartbeats();
+        }, this._heartbeatIntervalMs);
+        console.log(`[Group] heartbeat started: interval=${this._heartbeatIntervalMs}ms`);
+    }
+    /**
+     * 停止心跳定时器
+     */
+    _stopHeartbeat() {
+        if (this._heartbeatTimer) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
+            console.log(`[Group] heartbeat stopped`);
+        }
+    }
+    /**
+     * 对所有在线群组发送心跳
+     */
+    _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);
+            });
+        }
+    }
     /**
      * 关闭群消息存储，刷新所有未写入的数据
      */

package/dist/group/client.js

@@ -74,24 +74,21 @@ class ACPGroupClient {
      * Called by the message dispatch chain in AgentCP.
      */
     handleIncoming(payload) {
-        var _a, _b, _c;
-        // console.log(`[GroupClient] <<< handleIncoming raw payload (first 500 chars): ${payload.substring(0, 500)}`);
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
         let data;
         try {
             data = JSON.parse(payload);
         }
         catch (e) {
-            console.error(`[GroupClient] !!! JSON.parse failed for incoming payload:`, e, `payload(first 200): ${payload.substring(0, 200)}`);
+            console.error(`[GroupClient] JSON.parse failed for incoming payload:`, e);
             return;
         }
-        // console.log(`[GroupClient] <<< parsed data: action=${data.action} request_id=${data.request_id} event=${data.event} code=${data.code}`);
         // Try as response (has request_id)
         const requestId = (_a = data.request_id) !== null && _a !== void 0 ? _a : "";
         if (requestId) {
             const resp = (0, types_1.parseGroupResponse)(data);
             const pending = this._pendingReqs.get(requestId);
             if (pending) {
-                // console.log(`[GroupClient] <<< matched pending request: reqId=${requestId}, resolving`);
                 clearTimeout(pending.timer);
                 this._pendingReqs.delete(requestId);
                 pending.resolve(resp);
@@ -119,6 +116,34 @@ 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
+        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 (this._handler != null) {
+                (0, events_1.dispatchAcpNotify)(this._handler, notify);
+            }
+            else {
+                console.warn(`[GroupClient] !!! message_push dropped: no event handler registered.`);
+            }
+            return;
+        }
         console.warn(`[GroupClient] !!! unhandled incoming message: no request_id and no event field`, JSON.stringify(data).substring(0, 300));
     }
     // -- Lifecycle --

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, 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, 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 { ACPGroupClient, SendFunc } from './client';
 export { GroupOperations, SyncHandler } from './operations';
 export { ACPGroupEventHandler, EventProcessor, dispatchAcpNotify, dispatchEvent, } from './events';

package/dist/group/operations.d.ts

@@ -3,7 +3,7 @@
  * Mirrors Python SDK: agentcp/group/operations.py
  */
 import { ACPGroupClient } from './client';
-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';
+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';
 /**
  * Callback interface for syncGroup.
  */
@@ -42,15 +42,36 @@ export declare class GroupOperations {
         inviteCode?: string;
         message?: string;
     }): Promise<string>;
+    /**
+     * 注册上线，获取游标状态。
+     * 客户端每次启动或重新连接时，必须对每个群组调用。
+     */
+    registerOnline(targetAid: string, groupId: string): Promise<RegisterOnlineResp>;
+    /**
+     * 主动下线（优雅退出）。
+     * 客户端退出时调用，立即从在线列表移除。
+     */
+    unregisterOnline(targetAid: string, groupId: string): Promise<void>;
+    /**
+     * 心跳保活。
+     * 在线注册有 5 分钟超时，SDK 需定时发送（建议 2~4 分钟）。
+     */
+    heartbeat(targetAid: string, groupId: string): Promise<void>;
     createGroup(targetAid: string, name: string, options?: {
         alias?: string;
         subject?: string;
         visibility?: string;
+        description?: string;
         tags?: string[];
     }): Promise<CreateGroupResp>;
     addMember(targetAid: string, groupId: string, agentId: string, role?: string): Promise<void>;
     sendGroupMessage(targetAid: string, groupId: string, content: string, contentType?: string, metadata?: Record<string, any>): Promise<SendMessageResp>;
-    pullMessages(targetAid: string, groupId: string, afterMsgId: number, limit?: number): Promise<PullMessagesResp>;
+    /**
+     * 拉取消息。
+     * - afterMsgId > 0: 指定位置模式，从该 ID 之后开始拉取
+     * - afterMsgId = 0 或不传: 自动游标模式（推荐），服务端基于 current_msg_id 自动计算
+     */
+    pullMessages(targetAid: string, groupId: string, afterMsgId?: number, limit?: number): Promise<PullMessagesResp>;
     ackMessages(targetAid: string, groupId: string, msgId: number): Promise<void>;
     pullEvents(targetAid: string, groupId: string, afterEventId: number, limit?: number): Promise<PullEventsResp>;
     ackEvents(targetAid: string, groupId: string, eventId: number): Promise<void>;

package/dist/group/operations.js

@@ -59,6 +59,37 @@ class GroupOperations {
         return this.requestJoin(targetAid, groupId, (_a = options === null || options === void 0 ? void 0 : options.message) !== null && _a !== void 0 ? _a : '');
     }
     // ============================================================
+    // Phase 0: Lifecycle (register / heartbeat / unregister)
+    // ============================================================
+    /**
+     * 注册上线，获取游标状态。
+     * 客户端每次启动或重新连接时，必须对每个群组调用。
+     */
+    async registerOnline(targetAid, groupId) {
+        const resp = await this._client.sendRequest(targetAid, groupId, "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);
+        this._check(resp, "unregister_online");
+    }
+    /**
+     * 心跳保活。
+     * 在线注册有 5 分钟超时，SDK 需定时发送（建议 2~4 分钟）。
+     */
+    async heartbeat(targetAid, groupId) {
+        const resp = await this._client.sendRequest(targetAid, groupId, "heartbeat", null);
+        this._check(resp, "heartbeat");
+    }
+    // ============================================================
     // Phase 1: Basic Operations
     // ============================================================
     async createGroup(targetAid, name, options) {
@@ -70,6 +101,8 @@ class GroupOperations {
             params.subject = options.subject;
         if (options === null || options === void 0 ? void 0 : options.visibility)
             params.visibility = options.visibility;
+        if (options === null || options === void 0 ? void 0 : options.description)
+            params.description = options.description;
         if (options === null || options === void 0 ? void 0 : options.tags)
             params.tags = options.tags;
         const resp = await this._client.sendRequest(targetAid, "", "create_group", params);
@@ -96,12 +129,19 @@ class GroupOperations {
         const d = resp.data || {};
         return { msg_id: (_a = d.msg_id) !== null && _a !== void 0 ? _a : 0, timestamp: (_b = d.timestamp) !== null && _b !== void 0 ? _b : 0 };
     }
-    async pullMessages(targetAid, groupId, afterMsgId, limit = 0) {
+    /**
+     * 拉取消息。
+     * - afterMsgId > 0: 指定位置模式，从该 ID 之后开始拉取
+     * - afterMsgId = 0 或不传: 自动游标模式（推荐），服务端基于 current_msg_id 自动计算
+     */
+    async pullMessages(targetAid, groupId, afterMsgId = 0, limit = 0) {
         var _a, _b, _c;
-        const params = { after_msg_id: afterMsgId };
+        const params = {};
+        if (afterMsgId > 0)
+            params.after_msg_id = afterMsgId;
         if (limit > 0)
             params.limit = limit;
-        const resp = await this._client.sendRequest(targetAid, groupId, "pull_messages", params);
+        const resp = await this._client.sendRequest(targetAid, groupId, "pull_messages", Object.keys(params).length > 0 ? params : null);
         this._check(resp, "pull_messages");
         const d = resp.data || {};
         return {

package/dist/group/types.d.ts

@@ -85,6 +85,9 @@ export interface CursorState {
     msg_cursor: MsgCursor;
     event_cursor: EventCursor;
 }
+export interface RegisterOnlineResp {
+    msg_cursor: MsgCursor;
+}
 export interface CreateGroupResp {
     group_id: string;
     group_url: string;