@pnds/pond 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnds/pond",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "OpenClaw channel plugin for Pond IM",
   "license": "MIT",
   "repository": {
@@ -15,8 +15,8 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@pnds/sdk": "1.8.0",
-    "@pnds/cli": "1.8.0"
+    "@pnds/cli": "1.9.0",
+    "@pnds/sdk": "1.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/gateway.ts

@@ -402,7 +402,7 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
           }
         }
         // Resolve remaining items as not-dispatched (fork stopped after error).
-        // These events are NOT acked — inbox retains them for catch-up replay.
+        // These events are NOT acked — dispatch retains them for catch-up replay.
         for (const remaining of fork.queue.splice(0)) {
           remaining.resolve(false);
         }
@@ -535,10 +535,10 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
 
           dispatchState.mainCurrentTargetId = event.targetId;
           await runDispatch(event, orchestratorKey, bodyForAgent);
-          // Ack inbox after successful drain dispatch — these events were buffered
+          // Ack dispatch after successful drain — these events were buffered
           // without ack, so this is the first time they're confirmed processed.
           const sourceType = event.type === "task" ? "task_activity" : "message";
-          client.ackInbox(config.org_id, { source_type: sourceType, source_id: event.messageId }).catch(() => {});
+          client.ackDispatch(config.org_id, { source_type: sourceType, source_id: event.messageId }).catch(() => {});
         }
       } finally {
         draining = false;
@@ -550,8 +550,8 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     /**
      * Route and dispatch an inbound event.
      * Returns true if the event was dispatched (main or fork), false if only buffered.
-     * Callers should only ack inbox when this returns true — buffered events may be
-     * lost on crash and need to be replayed from inbox on the next catch-up.
+     * Callers should only ack dispatch when this returns true — buffered events may be
+     * lost on crash and need to be replayed from dispatch on the next catch-up.
      */
     async function handleInboundEvent(event: PondEvent): Promise<boolean> {
       const disposition = routeTrigger(event, dispatchState, defaultRoutingStrategy);
@@ -683,13 +683,13 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
           });
         }, intervalSec * 1000);
 
-        // Unified inbox catch-up (replaces separate mention/DM/task catch-up).
+        // Dispatch catch-up: fetch pending dispatch events (FIFO).
         // On cold start, skip items older than COLD_START_WINDOW_MS to avoid
         // replaying historical backlog from a previous process.
         const isFirstHello = !hadSuccessfulHello;
         hadSuccessfulHello = true;
-        catchUpFromInbox(isFirstHello).catch((err) => {
-          log?.warn(`pond[${ctx.accountId}]: inbox catch-up failed: ${String(err)}`);
+        catchUpFromDispatch(isFirstHello).catch((err) => {
+          log?.warn(`pond[${ctx.accountId}]: dispatch catch-up failed: ${String(err)}`);
         });
       } catch (err) {
         log?.error(`pond[${ctx.accountId}]: failed to fetch chats: ${String(err)}`);
@@ -757,7 +757,7 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
             (m) => m.user_id === agentUserId || m.user_id === MENTION_ALL_USER_ID,
           );
           if (!isMentioned) {
-            // Release claim so catch-up can process this via agent_route inbox items
+            // Release claim so catch-up can process this via dispatch events
             dispatchedMessages.delete(data.id);
             return;
           }
@@ -802,7 +802,7 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       try {
         const dispatched = await handleInboundEvent(event);
         if (dispatched) {
-          client.ackInbox(config.org_id, { source_type: "message", source_id: data.id }).catch(() => {});
+          client.ackDispatch(config.org_id, { source_type: "message", source_id: data.id }).catch(() => {});
         } else {
           // Not dispatched (buffered or fork failed) — release claim so catch-up can retry
           dispatchedMessages.delete(data.id);
@@ -861,7 +861,7 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     // Server event buffer overflowed — events were lost, trigger full catch-up
     ws.on("recovery.overflow", () => {
       log?.warn(`pond[${ctx.accountId}]: recovery.overflow — triggering full catch-up`);
-      catchUpFromInbox().catch((err) =>
+      catchUpFromDispatch().catch((err) =>
         log?.warn(`pond[${ctx.accountId}]: overflow catch-up failed: ${String(err)}`));
     });
 
@@ -871,33 +871,43 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       try {
         const dispatched = await handleTaskAssignment(data);
         if (dispatched) {
-          client.ackInbox(config.org_id, { source_type: "task_activity", source_id: data.id }).catch(() => {});
+          client.ackDispatch(config.org_id, { source_type: "task_activity", source_id: data.id }).catch(() => {});
         }
       } catch (err) {
         log?.error(`pond[${ctx.accountId}]: task dispatch failed for ${data.id}: ${String(err)}`);
       }
     });
 
-    // ── Unified inbox catch-up ──
-    // Replays missed mentions, DMs, and task assignments via the inbox API.
-    // Adapts each item into a PondEvent and routes through handleInboundEvent.
-    async function catchUpFromInbox(coldStart = false) {
+    // ── Dispatch catch-up ──
+    // Replays missed events via the dispatch API (agent-only endpoint, FIFO order).
+    // Each dispatch event is a source-pointer; we re-fetch the entity to build a PondEvent.
+    //
+    // Cold-start window: On a fresh process start (not reconnect), events older than
+    // COLD_START_WINDOW_MS are acked without processing. This is an intentional operator
+    // decision: a newly started agent should not replay unbounded historical backlog from
+    // a previous process lifetime. Reconnects (non-cold-start) replay all pending events.
+    //
+    // NOTE: RouteToAgents (active/smart group routing) inserts dispatch rows asynchronously
+    // after the message.new WS event. A race exists where the live ack-by-source fires
+    // before the dispatch row is inserted, leaving an orphan pending row. This is benign:
+    // catch-up will process it on next cycle (duplicate delivery, not data loss).
+    // TODO: resolve by creating dispatch rows before publishing the live event, or by
+    // consuming dispatch.new in the live path.
+    async function catchUpFromDispatch(coldStart = false) {
       const minAge = coldStart ? Date.now() - COLD_START_WINDOW_MS : 0;
       let cursor: string | undefined;
       let processed = 0;
       let skippedOld = 0;
 
       do {
-        const page = await client.getInbox(config.org_id, {
-          type: "mention,agent_dm,task_assign,agent_route",
-          read: "false",
+        const page = await client.getDispatch(config.org_id, {
           limit: 50,
           cursor,
         });
 
         for (const item of page.data ?? []) {
-          if (minAge > 0 && new Date(item.updated_at).getTime() < minAge) {
-            client.markInboxRead(config.org_id, item.id).catch(() => {});
+          if (minAge > 0 && new Date(item.created_at).getTime() < minAge) {
+            client.ackDispatchByID(config.org_id, item.id).catch(() => {});
             skippedOld++;
             continue;
           }
@@ -905,21 +915,59 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
           processed++;
           try {
             let dispatched = false;
-            if (item.type === "task_assign" && item.source_id) {
+            if (item.event_type === "task_assign" && item.task_id) {
               // Task catch-up: fetch full task and dispatch
-              const task = await client.getTask(config.org_id, item.source_id);
+              let task: Awaited<ReturnType<typeof client.getTask>> | null = null;
+              let taskFetchFailed = false;
+              try {
+                task = await client.getTask(config.org_id, item.task_id);
+              } catch (err: unknown) {
+                // Distinguish 404 (task deleted) from transient failures
+                const status = (err as { status?: number })?.status;
+                if (status === 404) {
+                  task = null; // task genuinely deleted
+                } else {
+                  taskFetchFailed = true;
+                  log?.warn(`pond[${ctx.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+                }
+              }
+              if (taskFetchFailed) {
+                continue; // leave pending for next catch-up cycle
+              }
               if (task) {
+                // Defense-in-depth (D2): verify task is still assigned to this agent
+                if (task.assignee_id !== agentUserId) {
+                  log?.info(`pond[${ctx.accountId}]: skipping stale task dispatch ${item.id} — reassigned to ${task.assignee_id}`);
+                  client.ackDispatchByID(config.org_id, item.id).catch(() => {});
+                  continue;
+                }
                 dispatched = await handleTaskAssignment(task);
               } else {
-                dispatched = true; // task deleted — mark read to prevent infinite retry
+                dispatched = true; // task genuinely deleted — ack to prevent infinite retry
               }
-            } else if (item.source_id && item.chat_id) {
-              // Message catch-up (mention or agent_dm): build PondEvent from inbox item
+            } else if (item.event_type === "message" && item.source_id && item.chat_id) {
+              // Message catch-up: build PondEvent from dispatch source pointer
               if (!tryClaimMessage(item.source_id)) continue;
-              const msg = await client.getMessage(item.source_id).catch(() => null);
+              let msg: Awaited<ReturnType<typeof client.getMessage>> | null = null;
+              let msgFetchFailed = false;
+              try {
+                msg = await client.getMessage(item.source_id);
+              } catch (err: unknown) {
+                const status = (err as { status?: number })?.status;
+                if (status === 404) {
+                  msg = null; // message genuinely deleted
+                } else {
+                  msgFetchFailed = true;
+                  log?.warn(`pond[${ctx.accountId}]: catch-up message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`);
+                }
+              }
+              if (msgFetchFailed) {
+                dispatchedMessages.delete(item.source_id);
+                continue; // leave pending for next catch-up cycle
+              }
               if (!msg || msg.sender_id === agentUserId) {
                 dispatchedMessages.delete(item.source_id);
-                client.markInboxRead(config.org_id, item.id).catch(() => {});
+                client.ackDispatchByID(config.org_id, item.id).catch(() => {});
                 continue;
               }
 
@@ -951,7 +999,7 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
               }
               if (!body) {
                 dispatchedMessages.delete(item.source_id);
-                client.markInboxRead(config.org_id, item.id).catch(() => {});
+                client.ackDispatchByID(config.org_id, item.id).catch(() => {});
                 continue;
               }
 
@@ -971,17 +1019,17 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
               dispatched = await handleInboundEvent(event);
             }
             if (dispatched) {
-              client.markInboxRead(config.org_id, item.id).catch(() => {});
+              client.ackDispatchByID(config.org_id, item.id).catch(() => {});
             }
           } catch (err) {
-            log?.warn(`pond[${ctx.accountId}]: catch-up item ${item.id} (${item.type}) failed: ${String(err)}`);
+            log?.warn(`pond[${ctx.accountId}]: catch-up dispatch ${item.id} (${item.event_type}) failed: ${String(err)}`);
           }
         }
         cursor = page.has_more ? page.next_cursor : undefined;
       } while (cursor);
 
       if (processed > 0 || skippedOld > 0) {
-        log?.info(`pond[${ctx.accountId}]: inbox catch-up: processed ${processed}, skipped ${skippedOld} old item(s)`);
+        log?.info(`pond[${ctx.accountId}]: dispatch catch-up: processed ${processed}, skipped ${skippedOld} old item(s)`);
       }
     }