@unicitylabs/openclaw-unicity 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unicitylabs/openclaw-unicity",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Unicity wallet identity and encrypted DMs for OpenClaw agents — powered by Sphere SDK",
   "type": "module",
   "main": "src/index.ts",

package/src/channel.ts

@@ -10,6 +10,24 @@ import type { UnicityConfig } from "./config.js";
 
 const DEFAULT_ACCOUNT_ID = "default";
 
+/** How long (ms) to wait after the last group message before declaring backfill complete. */
+export const GROUP_BACKFILL_DEBOUNCE_MS = 3_000;
+
+interface GroupBackfillState {
+  phase: "buffering" | "live";
+  latestMsg: {
+    id?: string;
+    groupId: string;
+    senderPubkey: string;
+    senderNametag?: string;
+    content: string;
+    timestamp: number;
+    replyToId?: string;
+  } | null;
+  bufferedCount: number;
+  timer: ReturnType<typeof setTimeout> | null;
+}
+
 // ---------------------------------------------------------------------------
 // Account config shape (read from openclaw config under channels.unicity)
 // ---------------------------------------------------------------------------
@@ -422,21 +440,22 @@ export const unicityChannelPlugin = {
           });
       });
 
-      // Subscribe to incoming group messages
-      const unsubGroupMessage = sphere.groupChat?.onMessage?.((msg: {
-        id: string;
+      // -- Group message dispatch helper & backfill debounce --------------------
+
+      type GroupMsg = {
+        id?: string;
         groupId: string;
-        groupName?: string;
         senderPubkey: string;
         senderNametag?: string;
         content: string;
-        timestamp?: number;
-      }) => {
-        // Skip messages from self
-        if (msg.senderPubkey === sphere.identity?.chainPubkey) return;
+        timestamp: number;
+        replyToId?: string;
+      };
 
+      function dispatchGroupMessage(msg: GroupMsg): void {
         const senderName = msg.senderNametag ?? msg.senderPubkey.slice(0, 12);
-        const groupName = msg.groupName ?? msg.groupId;
+        const groupData = sphere.groupChat?.getGroup?.(msg.groupId);
+        const groupName = groupData?.name ?? msg.groupId;
         const isOwner = isSenderOwner(msg.senderPubkey, msg.senderNametag);
         const metadataHeader = `[SenderName: ${senderName} | SenderId: ${msg.senderPubkey} | GroupId: ${msg.groupId} | GroupName: ${groupName} | IsOwner: ${isOwner} | CommandAuthorized: ${isOwner}]`;
         const sanitizedContent = msg.content.replace(/\[(?:SenderName|SenderId|IsOwner|CommandAuthorized|GroupId|GroupName)\s*:/gi, "[BLOCKED:");
@@ -487,40 +506,89 @@ export const unicityChannelPlugin = {
           .catch((err: unknown) => {
             ctx.log?.error(`[${ctx.account.accountId}] Group message dispatch error: ${err}`);
           });
+      }
+
+      // Per-group backfill state: buffer messages during the initial burst, then
+      // switch to live dispatch once the burst settles.
+      const groupBackfillStates = new Map<string, GroupBackfillState>();
+
+      // Subscribe to incoming group messages
+      const unsubGroupMessage = sphere.groupChat?.onMessage?.((msg: GroupMsg) => {
+        // Skip messages from self
+        if (msg.senderPubkey === sphere.identity?.chainPubkey) return;
+
+        // Lookup or create per-group backfill state
+        let state = groupBackfillStates.get(msg.groupId);
+        if (!state) {
+          state = { phase: "buffering", latestMsg: null, bufferedCount: 0, timer: null };
+          groupBackfillStates.set(msg.groupId, state);
+        }
+
+        // Already past backfill — dispatch immediately
+        if (state.phase === "live") {
+          dispatchGroupMessage(msg);
+          return;
+        }
+
+        // BUFFERING: keep only the latest message, reset the debounce timer
+        state.latestMsg = msg;
+        state.bufferedCount++;
+        if (state.timer) clearTimeout(state.timer);
+        state.timer = setTimeout(() => {
+          state!.phase = "live";
+          state!.timer = null;
+          ctx.log?.info(
+            `[${ctx.account.accountId}] Group backfill settled for ${msg.groupId}, ${state!.bufferedCount} message(s) buffered`,
+          );
+          // Dispatch the most recent buffered message so the agent has context
+          if (state!.latestMsg) {
+            dispatchGroupMessage(state!.latestMsg);
+            state!.latestMsg = null;
+          }
+        }, GROUP_BACKFILL_DEBOUNCE_MS);
       }) ?? (() => {});
 
       // Subscribe to group lifecycle events and notify owner
-      const unsubGroupJoined = sphere.on?.("groupchat:joined", (event: { id: string; name?: string }) => {
+      const unsubGroupJoined = sphere.on?.("groupchat:joined", (event: { groupId: string; groupName: string }) => {
         const owner = getOwnerIdentity();
         if (owner) {
-          const label = event.name ? `${event.name} (${event.id})` : event.id;
+          const label = event.groupName ? `${event.groupName} (${event.groupId})` : event.groupId;
           sphere.communications.sendDM(`@${owner}`, `I joined group ${label}`).catch((err) => {
             ctx.log?.error(`[${ctx.account.accountId}] Failed to notify owner about group join: ${err}`);
           });
         }
       }) ?? (() => {});
 
-      const unsubGroupLeft = sphere.on?.("groupchat:left", (event: { id: string; name?: string }) => {
+      const unsubGroupLeft = sphere.on?.("groupchat:left", (event: { groupId: string }) => {
         const owner = getOwnerIdentity();
         if (owner) {
-          const label = event.name ?? event.id;
+          const groupData = sphere.groupChat?.getGroup?.(event.groupId);
+          const label = groupData?.name ?? event.groupId;
           sphere.communications.sendDM(`@${owner}`, `I left group ${label}`).catch((err) => {
             ctx.log?.error(`[${ctx.account.accountId}] Failed to notify owner about group leave: ${err}`);
           });
         }
       }) ?? (() => {});
 
-      const unsubGroupKicked = sphere.on?.("groupchat:kicked", (event: { id: string; name?: string }) => {
+      const unsubGroupKicked = sphere.on?.("groupchat:kicked", (event: { groupId: string; groupName: string }) => {
         const owner = getOwnerIdentity();
         if (owner) {
-          const label = event.name ?? event.id;
+          const label = event.groupName ? `${event.groupName} (${event.groupId})` : event.groupId;
           sphere.communications.sendDM(`@${owner}`, `I was kicked from group ${label}`).catch((err) => {
             ctx.log?.error(`[${ctx.account.accountId}] Failed to notify owner about group kick: ${err}`);
           });
         }
       }) ?? (() => {});
 
+      function clearBackfillTimers(): void {
+        for (const state of groupBackfillStates.values()) {
+          if (state.timer) clearTimeout(state.timer);
+        }
+        groupBackfillStates.clear();
+      }
+
       ctx.abortSignal.addEventListener("abort", () => {
+        clearBackfillTimers();
         unsub();
         unsubTransfer();
         unsubPaymentRequest();
@@ -532,6 +600,7 @@ export const unicityChannelPlugin = {
 
       return {
         stop: () => {
+          clearBackfillTimers();
           unsub();
           unsubTransfer();
           unsubPaymentRequest();

package/src/tools/create-private-group.ts

@@ -28,8 +28,10 @@ export const createPrivateGroupTool = {
       visibility: "private",
     });
 
-    const invite = await sphere.groupChat.createInvite(group.id);
-    const joinCode = invite.code;
+    const joinCode = await sphere.groupChat.createInvite(group.id);
+    if (!joinCode) {
+      throw new Error("Failed to generate invite code for the private group");
+    }
 
     const lines = [
       `Private group created: ${group.name} (${group.id})`,