@pnds/pond 1.7.0 → 1.9.0

package/package.json

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

package/src/gateway.ts

@@ -34,7 +34,7 @@ function resolveWsUrl(account: ResolvedPondAccount): string {
   return `${wsBase}/ws`;
 }
 
-type ChatInfo = { type: Chat["type"]; name: string | null };
+type ChatInfo = { type: Chat["type"]; name: string | null; agentRoutingMode: Chat["agent_routing_mode"] };
 
 /**
  * Fetch all chats with pagination and populate the info map (type + name).
@@ -49,7 +49,7 @@ async function fetchAllChats(
   do {
     const res = await client.getChats(orgId, { limit: 100, cursor });
     for (const c of res.data) {
-      chatInfoMap.set(c.id, { type: c.type, name: c.name ?? null });
+      chatInfoMap.set(c.id, { type: c.type, name: c.name ?? null, agentRoutingMode: c.agent_routing_mode });
     }
     total += res.data.length;
     cursor = res.has_more ? res.next_cursor : undefined;
@@ -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)}`);
@@ -700,13 +700,19 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       const changes = data.changes as Record<string, unknown> | undefined;
       if (!changes) return;
       const existing = chatInfoMap.get(data.chat_id);
-      if (typeof changes.type === "string") {
+      if (existing) {
+        chatInfoMap.set(data.chat_id, {
+          ...existing,
+          ...(typeof changes.type === "string" ? { type: changes.type as Chat["type"] } : {}),
+          ...(typeof changes.name === "string" ? { name: changes.name } : {}),
+          ...(typeof changes.agent_routing_mode === "string" ? { agentRoutingMode: changes.agent_routing_mode as Chat["agent_routing_mode"] } : {}),
+        });
+      } else if (typeof changes.type === "string") {
         chatInfoMap.set(data.chat_id, {
           type: changes.type as Chat["type"],
-          name: (typeof changes.name === "string" ? changes.name : existing?.name) ?? null,
+          name: (typeof changes.name === "string" ? changes.name : null),
+          agentRoutingMode: (typeof changes.agent_routing_mode === "string" ? changes.agent_routing_mode : "passive") as Chat["agent_routing_mode"],
         });
-      } else if (typeof changes.name === "string" && existing) {
-        chatInfoMap.set(data.chat_id, { ...existing, name: changes.name });
       }
     });
 
@@ -724,7 +730,7 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       if (!chatInfo) {
         try {
           const chat = await client.getChat(config.org_id, chatId);
-          chatInfo = { type: chat.type, name: chat.name ?? null };
+          chatInfo = { type: chat.type, name: chat.name ?? null, agentRoutingMode: chat.agent_routing_mode };
           chatInfoMap.set(chatId, chatInfo);
         } catch (err) {
           log?.warn(`pond[${ctx.accountId}]: failed to resolve chat for ${chatId}, skipping: ${String(err)}`);
@@ -741,17 +747,27 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
         body = content.text?.trim() ?? "";
         if (!body) return;
 
-        // In group chats, only respond when @mentioned or @all
-        if (chatInfo.type === "group") {
+        // In group chats, respond based on agent_routing_mode:
+        // - passive (default): only when @mentioned or @all
+        // - active: all messages dispatched via live handler
+        // - smart: skip live handler — server decides routing via inbox items
+        if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
           const mentions = content.mentions ?? [];
           const isMentioned = mentions.some(
             (m) => m.user_id === agentUserId || m.user_id === MENTION_ALL_USER_ID,
           );
-          if (!isMentioned) return;
+          if (!isMentioned) {
+            // Release claim so catch-up can process this via dispatch events
+            dispatchedMessages.delete(data.id);
+            return;
+          }
         }
       } else {
         const content = data.content as MediaContent;
-        if (chatInfo.type === "group") return;
+        if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+          dispatchedMessages.delete(data.id);
+          return;
+        }
         body = content.caption?.trim() || `[file: ${content.file_name || "attachment"}]`;
         if (content.attachment_id) {
           try {
@@ -786,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);
@@ -845,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)}`));
     });
 
@@ -855,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",
-          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;
           }
@@ -889,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;
               }
 
@@ -911,7 +975,7 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
               if (!chatInfo) {
                 try {
                   const chat = await client.getChat(config.org_id, item.chat_id);
-                  chatInfo = { type: chat.type, name: chat.name ?? null };
+                  chatInfo = { type: chat.type, name: chat.name ?? null, agentRoutingMode: chat.agent_routing_mode };
                   chatInfoMap.set(item.chat_id, chatInfo);
                 } catch {
                   dispatchedMessages.delete(item.source_id);
@@ -935,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;
               }
 
@@ -955,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)`);
       }
     }