@pnds/pond 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnds/pond",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "OpenClaw channel plugin for Pond IM",
   "license": "MIT",
   "repository": {
@@ -14,7 +14,7 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@pnds/sdk": "1.0.0"
+    "@pnds/sdk": "1.1.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0"

package/src/gateway.ts

@@ -38,6 +38,60 @@ async function fetchAllChats(
   return total;
 }
 
+/**
+ * Fetch recent messages from a chat (or thread) and format them as a history context block.
+ * Pass threadRootId to scope to a thread; omit (or null) to fetch top-level messages only.
+ * Returns empty string on failure or timeout (non-fatal).
+ */
+async function buildChatHistoryContext(
+  client: PondClient,
+  orgId: string,
+  chatId: string,
+  beforeMessageId: string,
+  agentUserId: string,
+  limit: number = 30,
+  log?: { warn: (msg: string) => void },
+  threadRootId?: string | null,
+): Promise<string> {
+  try {
+    const threadParams = threadRootId
+      ? { thread_root_id: threadRootId }
+      : { top_level: true as const };
+    const res = await client.getMessages(orgId, chatId, { before: beforeMessageId, limit, ...threadParams });
+    if (!res.data.length) return "";
+
+    const escapeHistoryValue = (value: string): string =>
+      value
+        .replace(/\r?\n/g, "\\n")
+        .replace(/\[Recent chat history\]|\[End of chat history\]/g, (m) => `\\${m}`);
+
+    const lines: string[] = [];
+    for (const msg of res.data) {
+      if (msg.message_type !== "text" && msg.message_type !== "file") continue;
+      const senderLabel = escapeHistoryValue(msg.sender?.display_name ?? msg.sender_id);
+      const role = msg.sender_id === agentUserId ? "You" : senderLabel;
+
+      if (msg.message_type === "text") {
+        const content = msg.content as TextContent;
+        const text = escapeHistoryValue(content.text?.trim() ?? "");
+        if (text) lines.push(`${role}: ${text}`);
+      } else {
+        const content = msg.content as MediaContent;
+        const caption = escapeHistoryValue(
+          content.caption?.trim() || `[file: ${content.file_name || "attachment"}]`,
+        );
+        lines.push(`${role}: ${caption}`);
+      }
+    }
+
+    if (!lines.length) return "";
+    return `[Recent chat history]\n${lines.join("\n")}\n[End of chat history]\n\n`;
+  } catch (err) {
+    log?.warn(`pond: failed to fetch chat history for context: ${String(err)}`);
+    return "";
+  }
+}
+
 /**
  * Dispatch an inbound message to the OpenClaw agent and handle the reply.
  * Shared by both text and file message handlers to avoid duplication.
@@ -49,29 +103,65 @@ async function dispatchToAgent(opts: {
   config: PondChannelConfig;
   agentUserId: string;
   accountId: string;
+  sessionKey: string;
   chatId: string;
   messageId: string;
   inboundCtx: Record<string, unknown>;
+  noReply?: boolean;
   log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
 }) {
-  const { core, cfg, client, config, agentUserId, accountId, chatId, messageId, inboundCtx, log } = opts;
+  const { core, cfg, client, config, agentUserId, accountId, sessionKey, chatId, messageId, inboundCtx, noReply, log } = opts;
+  const sessionKeyLower = sessionKey.toLowerCase();
   let thinkingSent = false;
   let runIdPromise: Promise<string | undefined> | undefined;
+  let reasoningBuffer = "";
   try {
     await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
       ctx: inboundCtx,
       cfg,
       dispatcherOptions: {
-        deliver: async (payload: { text?: string }) => {
+        deliver: async (payload: { text?: string }, info: { kind: string }) => {
           const replyText = payload.text?.trim();
           if (!replyText) return;
           // Wait for run creation to complete before sending
           const runId = runIdPromise ? await runIdPromise : undefined;
-          await client.sendMessage(config.org_id, chatId, {
-            message_type: "text",
-            content: { text: replyText },
-            agent_run_id: runId,
-          });
+
+          if (info.kind === "final") {
+            if (noReply) {
+              // no_reply: unconditionally suppress chat output; runId only affects step recording
+              if (runId) {
+                try {
+                  await client.createAgentStep(config.org_id, agentUserId, runId, {
+                    step_type: "text",
+                    content: { text: replyText, suppressed: true },
+                  });
+                } catch (err) {
+                  log?.warn(`pond[${accountId}]: failed to create suppressed text step: ${String(err)}`);
+                }
+              } else {
+                log?.warn(`pond[${accountId}]: suppressing final reply but no runId available`);
+              }
+              return;
+            }
+            // Normal: final reply → chat message
+            await client.sendMessage(config.org_id, chatId, {
+              message_type: "text",
+              content: { text: replyText },
+              agent_run_id: runId,
+            });
+          } else if (info.kind === "block" && runId) {
+            // Intermediate text → step with chat_projection hint (server decides)
+            try {
+              await client.createAgentStep(config.org_id, agentUserId, runId, {
+                step_type: "text",
+                content: { text: replyText },
+                chat_projection: true,
+              });
+            } catch (err) {
+              log?.warn(`pond[${accountId}]: failed to create text step: ${String(err)}`);
+            }
+          }
+          // kind === "tool" → ignore (handled by hooks)
         },
         onReplyStart: () => {
           if (thinkingSent) return;
@@ -83,18 +173,34 @@ async function dispatchToAgent(opts: {
                 trigger_ref: { message_id: messageId },
                 chat_id: chatId,
               });
-              const state = getPondAccountState(accountId);
-              if (state) state.activeRunId = run.id;
-              await client.createAgentStep(config.org_id, agentUserId, run.id, {
-                step_type: "thinking",
-                content: { text: "" },
-              });
               return run.id;
             } catch (err) {
               log?.warn(`pond[${accountId}]: failed to create agent run: ${String(err)}`);
               return undefined;
             }
           })();
+          // Store promise immediately so hooks can await it before the run is created
+          const state = getPondAccountState(accountId);
+          if (state) state.activeRuns.set(sessionKeyLower, runIdPromise);
+        },
+      },
+      replyOptions: {
+        onReasoningStream: (payload: { text?: string }) => {
+          reasoningBuffer += payload.text ?? "";
+        },
+        onReasoningEnd: async () => {
+          const runId = runIdPromise ? await runIdPromise : undefined;
+          if (runId && reasoningBuffer) {
+            try {
+              await client.createAgentStep(config.org_id, agentUserId, runId, {
+                step_type: "thinking",
+                content: { text: reasoningBuffer },
+              });
+            } catch (err) {
+              log?.warn(`pond[${accountId}]: failed to create thinking step: ${String(err)}`);
+            }
+          }
+          reasoningBuffer = "";
         },
       },
     });
@@ -161,6 +267,10 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     let sessionId = "";
     // Heartbeat interval handle — created inside hello handler with server-provided interval
     let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+    // Track active dispatches per chat for typing indicator management
+    const activeDispatches = new Map<string, { count: number; typingTimer: ReturnType<typeof setInterval> }>();
+    // Heartbeat watchdog: detect event loop blocking during long CC runs
+    let lastHeartbeatAt = Date.now();
 
     // Log connection state changes (covers reconnection)
     ws.onStateChange((state) => {
@@ -180,11 +290,20 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
           client,
           orgId: config.org_id,
           agentUserId,
+          activeRuns: new Map(),
         });
 
         // (Re)start heartbeat with server-provided interval
         if (heartbeatTimer) clearInterval(heartbeatTimer);
+        lastHeartbeatAt = Date.now();
         heartbeatTimer = setInterval(() => {
+          const now = Date.now();
+          const expectedMs = intervalSec * 1000;
+          const drift = now - lastHeartbeatAt - expectedMs;
+          if (drift > 15000) {
+            log?.warn(`pond[${ctx.accountId}]: heartbeat drift ${drift}ms — event loop may be blocked`);
+          }
+          lastHeartbeatAt = now;
           if (ws.state !== "connected") return;
           ws.sendAgentHeartbeat(sessionId, {
             hostname: os.hostname(),
@@ -201,8 +320,9 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
 
     // Track chat type changes (new chats, renames, etc.)
     ws.on("chat.update", (data: ChatUpdateData) => {
-      if (data.changes && typeof data.changes.type === "string") {
-        chatTypeMap.set(data.chat_id, data.changes.type as Chat["type"]);
+      const changes = data.changes as Record<string, unknown> | undefined;
+      if (changes && typeof changes.type === "string") {
+        chatTypeMap.set(data.chat_id, changes.type as Chat["type"]);
       }
     });
 
@@ -271,10 +391,32 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       const sessionKey = buildSessionKey(ctx.accountId, chatType, chatId);
       setSessionChatId(sessionKey, chatId);
 
+      // Start typing indicator immediately before any async work so the user
+      // sees feedback right away. Reference-counted for concurrent dispatches.
+      const existingDispatchEarly = activeDispatches.get(chatId);
+      if (existingDispatchEarly) {
+        existingDispatchEarly.count++;
+      } else {
+        if (ws.state === "connected") ws.sendTyping(chatId, "start");
+        // Frontend auto-clears typing after 3s, so refresh at 2s to avoid flicker
+        const typingRefresh = setInterval(() => {
+          if (ws.state === "connected") ws.sendTyping(chatId, "start");
+        }, 2000);
+        activeDispatches.set(chatId, { count: 1, typingTimer: typingRefresh });
+      }
+
+      // Fetch history with a 2s timeout — degrade gracefully to empty on slow API
+      const historyTimeout = new Promise<string>((resolve) => setTimeout(() => resolve(""), 2000));
+      const historyFetch = buildChatHistoryContext(
+        client, config.org_id, chatId, data.id, agentUserId, 30, log,
+        data.thread_root_id,
+      );
+      const historyPrefix = await Promise.race([historyFetch, historyTimeout]);
+
       // Build inbound context for OpenClaw agent
       const inboundCtx = core.channel.reply.finalizeInboundContext({
         Body: body,
-        BodyForAgent: body,
+        BodyForAgent: historyPrefix ? `${historyPrefix}${body}` : body,
         RawBody: body,
         CommandBody: body,
         ...mediaFields,
@@ -294,18 +436,35 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
         OriginatingTo: `pond:${chatId}`,
       });
 
-      await dispatchToAgent({
-        core,
-        cfg: ctx.cfg,
-        client,
-        config,
-        agentUserId,
-        accountId: ctx.accountId,
-        chatId,
-        messageId: data.id,
-        inboundCtx,
-        log,
-      });
+      // Extract no_reply hint from message
+      const noReply = data.hints?.no_reply ?? false;
+
+      try {
+        await dispatchToAgent({
+          core,
+          cfg: ctx.cfg,
+          client,
+          config,
+          agentUserId,
+          accountId: ctx.accountId,
+          sessionKey,
+          chatId,
+          messageId: data.id,
+          inboundCtx,
+          noReply,
+          log,
+        });
+      } finally {
+        const dispatch = activeDispatches.get(chatId);
+        if (dispatch) {
+          dispatch.count--;
+          if (dispatch.count <= 0) {
+            clearInterval(dispatch.typingTimer);
+            activeDispatches.delete(chatId);
+            if (ws.state === "connected") ws.sendTyping(chatId, "stop");
+          }
+        }
+      }
     });
 
     // Re-apply platform config when server pushes an update notification
@@ -324,6 +483,11 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     // Clean up on abort
     ctx.abortSignal.addEventListener("abort", () => {
       if (heartbeatTimer) clearInterval(heartbeatTimer);
+      // Clean up all active typing timers to prevent leaks
+      for (const [, dispatch] of activeDispatches) {
+        clearInterval(dispatch.typingTimer);
+      }
+      activeDispatches.clear();
       ws.disconnect();
       removePondAccountState(ctx.accountId);
       // Clear injected env vars so stale credentials don't leak to future subprocesses

package/src/hooks.ts

@@ -1,12 +1,13 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { extractAccountIdFromSessionKey } from "./session.js";
-import { getPondAccountState, getSessionChatId } from "./runtime.js";
+import { getActiveRunId, getPondAccountState, getSessionChatId } from "./runtime.js";
 
 /**
  * Resolve the PondClient + orgId + runId for a hook context.
- * Matches by accountId extracted from the session key.
+ * Awaits the run ID promise so hooks that fire before createAgentRun
+ * completes will block until the run ID is available (not silently drop).
  */
-function resolveClientForHook(sessionKey: string | undefined) {
+async function resolveClientForHook(sessionKey: string | undefined) {
   if (!sessionKey) return undefined;
   // Use stored mapping to recover original (case-sensitive) chat ID,
   // because openclaw normalizes session keys to lowercase.
@@ -17,7 +18,10 @@ function resolveClientForHook(sessionKey: string | undefined) {
 
   const state = getPondAccountState(accountId);
   if (!state) return undefined;
-  return { ...state, chatId };
+
+  // Await the run ID promise — may block briefly if the run is still being created
+  const activeRunId = await getActiveRunId(state, sessionKey);
+  return { ...state, chatId, activeRunId };
 }
 
 const POND_CLI_CONTEXT = `## Pond CLI
@@ -26,9 +30,13 @@ You have access to the Pond platform via the \`@pnds/cli\` CLI. Auth is pre-conf
 
 \`\`\`
 npx @pnds/cli@latest whoami                          # Check your identity
+npx @pnds/cli@latest agents list                     # List all agents (name, model, status)
+npx @pnds/cli@latest dm <name-or-id> --text "..."    # DM a user by name or ID (auto-creates chat)
+npx @pnds/cli@latest dm <name-or-id> --text "..." --no-reply  # DM, signal no reply expected
 npx @pnds/cli@latest chats list                      # List chats
 npx @pnds/cli@latest messages list <chatId>          # Read chat history
 npx @pnds/cli@latest messages send <chatId> --text "..." # Send a message
+npx @pnds/cli@latest messages send <chatId> --text "..." --no-reply  # Send, no reply expected
 npx @pnds/cli@latest tasks list [--status ...]       # List tasks
 npx @pnds/cli@latest tasks create --title "..."      # Create a task
 npx @pnds/cli@latest tasks update <taskId> --status in_progress
@@ -37,7 +45,14 @@ npx @pnds/cli@latest users search <query>            # Find users
 npx @pnds/cli@latest members list                    # List org members
 \`\`\`
 
-Run \`npx @pnds/cli@latest --help\` or \`npx @pnds/cli@latest <command> --help\` for full options. Output is JSON.`;
+Run \`npx @pnds/cli@latest --help\` or \`npx @pnds/cli@latest <command> --help\` for full options. Output is JSON.
+
+## Agent-to-Agent Interaction
+
+When you receive a message from another agent (not a human):
+- If the message has a no_reply hint, you may still reason and use tools, but your response will not be sent to chat.
+- If you have nothing meaningful to add to the conversation, produce an empty response to avoid unnecessary back-and-forth.
+- Use --no-reply when sending messages that don't require a response (e.g., delivering results, FYI notifications).`;
 
 export function registerPondHooks(api: OpenClawPluginApi) {
   const log = api.logger;
@@ -48,33 +63,38 @@ export function registerPondHooks(api: OpenClawPluginApi) {
   });
 
   // before_tool_call -> send tool_call step to AgentRun
-  api.on("before_tool_call", async (event, ctx) => {
-    const resolved = resolveClientForHook(ctx.sessionKey);
-    if (!resolved || !resolved.activeRunId) return;
-    try {
-      await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
-        step_type: "tool_call",
-        content: {
-          tool_name: event.toolName,
-          tool_input: event.params ?? {},
-          status: "running",
-          started_at: new Date().toISOString(),
-        },
-      });
-    } catch (err) {
-      log?.warn(`pond hook before_tool_call failed: ${String(err)}`);
-    }
+  // Fire-and-forget: before_tool_call is an awaited hook in OpenClaw (can block/modify
+  // tool params), so we must not block tool execution waiting for run creation.
+  api.on("before_tool_call", (event, ctx) => {
+    void (async () => {
+      const resolved = await resolveClientForHook(ctx.sessionKey);
+      if (!resolved || !resolved.activeRunId || !event.toolCallId) return;
+      try {
+        await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
+          step_type: "tool_call",
+          content: {
+            call_id: event.toolCallId,
+            tool_name: event.toolName,
+            tool_input: event.params ?? {},
+            status: "running",
+            started_at: new Date().toISOString(),
+          },
+        });
+      } catch (err) {
+        log?.warn(`pond hook before_tool_call failed: ${String(err)}`);
+      }
+    })();
   });
 
   // after_tool_call -> send tool_result step to AgentRun
   api.on("after_tool_call", async (event, ctx) => {
-    const resolved = resolveClientForHook(ctx.sessionKey);
-    if (!resolved || !resolved.activeRunId) return;
+    const resolved = await resolveClientForHook(ctx.sessionKey);
+    if (!resolved || !resolved.activeRunId || !event.toolCallId) return;
     try {
       await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
         step_type: "tool_result",
         content: {
-          tool_call_id: event.toolCallId ?? "",
+          call_id: event.toolCallId,
           tool_name: event.toolName,
           status: event.error ? "error" : "success",
           output: event.error ?? (typeof event.result === "string" ? event.result : JSON.stringify(event.result ?? "")),
@@ -89,23 +109,25 @@ export function registerPondHooks(api: OpenClawPluginApi) {
 
   // agent_end -> complete the AgentRun
   api.on("agent_end", async (_event, ctx) => {
-    const resolved = resolveClientForHook(ctx.sessionKey);
+    const resolved = await resolveClientForHook(ctx.sessionKey);
     if (!resolved) {
       log?.warn(`pond hook agent_end: could not resolve client (sessionKey=${ctx.sessionKey})`);
       return;
     }
     if (!resolved.activeRunId) return;
+    const accountId = extractAccountIdFromSessionKey(ctx.sessionKey ?? "");
+    const state = accountId ? getPondAccountState(accountId) : undefined;
     try {
       await resolved.client.updateAgentRun(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
         status: "completed",
       });
-      // Clear the active run
-      const state = getPondAccountState(
-        extractAccountIdFromSessionKey(ctx.sessionKey ?? "") ?? "",
-      );
-      if (state) state.activeRunId = undefined;
     } catch (err) {
       log?.warn(`pond hook agent_end failed: ${String(err)}`);
+    } finally {
+      // Always clear local state — even if the server call failed, the run is over locally
+      if (state && ctx.sessionKey) {
+        state.activeRuns.delete(ctx.sessionKey.toLowerCase());
+      }
     }
   });
 }

package/src/outbound.ts

@@ -1,6 +1,6 @@
 import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
 import { resolvePondAccount } from "./accounts.js";
-import { getPondAccountState } from "./runtime.js";
+import { getPondAccountState, getSessionChatId } from "./runtime.js";
 import { PondClient } from "@pnds/sdk";
 import type { SendMessageRequest } from "@pnds/sdk";
 
@@ -22,10 +22,21 @@ export const pondOutbound: ChannelOutboundAdapter = {
     const orgId = state?.orgId ?? account.config.org_id;
     const chatId = to;
 
+    // Match active run by chatId (outbound path has no sessionKey, but has chatId via `to`)
+    let agentRunId: string | undefined;
+    if (state) {
+      for (const [sessionKey, runPromise] of state.activeRuns.entries()) {
+        if (getSessionChatId(sessionKey) === chatId) {
+          agentRunId = await runPromise;
+          break;
+        }
+      }
+    }
+
     const req: SendMessageRequest = {
       message_type: "text",
       content: { text },
-      agent_run_id: state?.activeRunId,
+      agent_run_id: agentRunId,
     };
     const msg = await client.sendMessage(orgId, chatId, req);
     return { channel: "pond", messageId: msg.id, channelId: chatId };

package/src/runtime.ts

@@ -19,9 +19,18 @@ export type PondAccountState = {
   client: PondClient;
   orgId: string;
   agentUserId: string;
-  activeRunId?: string; // current AgentRun ID, set by gateway on reply start
+  activeRuns: Map<string, Promise<string | undefined>>; // sessionKey (lowercased) → runId promise
 };
 
+/** Resolve run ID for a session, awaiting if the run is still being created. */
+export async function getActiveRunId(
+  state: PondAccountState,
+  sessionKey: string,
+): Promise<string | undefined> {
+  const promise = state.activeRuns.get(sessionKey.toLowerCase());
+  return promise ? await promise : undefined;
+}
+
 const accountStates = new Map<string, PondAccountState>();
 
 export function setPondAccountState(accountId: string, state: PondAccountState) {