@pnds/pond 1.9.0 → 1.10.0

package/package.json

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

package/src/gateway.ts

@@ -6,6 +6,7 @@ type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>["gateway"
 import { PondClient, PondWs, MENTION_ALL_USER_ID } from "@pnds/sdk";
 import type { Chat, MessageNewData, TextContent, MediaContent, HelloData, ChatUpdateData, AgentConfigUpdateData, TaskAssignedData, Task } from "@pnds/sdk";
 import type { PondChannelConfig } from "./types.js";
+import * as crypto from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolvePondAccount } from "./accounts.js";
@@ -18,6 +19,8 @@ import {
   setSessionMessageId,
   setDispatchMessageId,
   setDispatchNoReply,
+  setDispatchGroupKey,
+  clearDispatchGroupKey,
 } from "./runtime.js";
 import type { PondEvent, DispatchState, ForkResult } from "./runtime.js";
 import { buildOrchestratorSessionKey } from "./session.js";
@@ -95,7 +98,6 @@ function buildForkResultPrefix(results: ForkResult[]): string {
     const lines = [`[Fork result]`];
     lines.push(`[Handled: ${r.sourceEvent.type} — ${r.sourceEvent.summary}]`);
     if (r.actions.length) lines.push(`[Actions: ${r.actions.join("; ")}]`);
-    if (r.agentRunId) lines.push(`[Agent run: ${r.agentRunId}]`);
     return lines.join("\n");
   });
   return blocks.join("\n\n") + "\n\n---\n\n";
@@ -118,60 +120,72 @@ async function dispatchToAgent(opts: {
   triggerType?: string;
   triggerRef?: Record<string, unknown>;
   chatId?: string;
-  /** For task dispatches: bind the run to a task target for Redis presence + fallback comments. */
   defaultTargetType?: string;
   defaultTargetId?: string;
+  senderId?: string;
+  senderName?: string;
+  messageBody?: string;
   log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
 }) {
   const { core, cfg, client, config, agentUserId, accountId, sessionKey, messageId, inboundCtx, log } = opts;
   const triggerType = opts.triggerType ?? "mention";
   const triggerRef = opts.triggerRef ?? { message_id: messageId };
-  const sessionKeyLower = sessionKey.toLowerCase();
-  let thinkingSent = false;
-  let runIdPromise: Promise<string | undefined> | undefined;
+
+  // Resolve session ID from account state
+  const state = getPondAccountState(accountId);
+  const sessionId = state?.activeSessionId;
+
+  // Create input step — captures the user message as a step in the session
+  if (sessionId) {
+    const targetType = opts.chatId ? "chat" : opts.defaultTargetType ?? "";
+    const targetId = opts.chatId ?? opts.defaultTargetId;
+    try {
+      await client.createAgentStep(config.org_id, agentUserId, sessionId, {
+        step_type: "input",
+        target_type: targetType,
+        target_id: targetId,
+        content: {
+          trigger_type: triggerType,
+          trigger_ref: triggerRef,
+          sender_id: opts.senderId ?? "",
+          sender_name: opts.senderName ?? "",
+          summary: opts.messageBody?.substring(0, 200) ?? "",
+        },
+      });
+    } catch (err) {
+      log?.warn(`pond[${accountId}]: failed to create input step: ${String(err)}`);
+    }
+  }
+
   let reasoningBuffer = "";
+  let turnGroupKey = "";
   try {
     await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
       ctx: inboundCtx,
       cfg,
       dispatcherOptions: {
-        deliver: async (payload: { text?: string }, info: { kind: string }) => {
+        deliver: async (payload: { text?: string }) => {
           // Orchestrator mode: ALL text output is suppressed — agent uses tools to interact.
           // Record as internal step for observability.
           const replyText = payload.text?.trim();
-          if (!replyText) return;
-          const runId = runIdPromise ? await runIdPromise : undefined;
-          if (runId) {
-            try {
-              await client.createAgentStep(config.org_id, agentUserId, runId, {
-                step_type: "text",
-                content: { text: replyText, suppressed: true },
-                ...(info.kind === "block" ? { chat_projection: false } : {}),
-              });
-            } catch (err) {
-              log?.warn(`pond[${accountId}]: failed to create suppressed text step: ${String(err)}`);
-            }
+          if (!replyText || !sessionId) return;
+          const targetType = opts.chatId ? "chat" : opts.defaultTargetType ?? "";
+          const targetId = opts.chatId ?? opts.defaultTargetId;
+          try {
+            await client.createAgentStep(config.org_id, agentUserId, sessionId, {
+              step_type: "text",
+              target_type: targetType,
+              target_id: targetId,
+              content: { text: replyText, suppressed: true },
+            });
+          } catch (err) {
+            log?.warn(`pond[${accountId}]: failed to create suppressed text step: ${String(err)}`);
           }
         },
         onReplyStart: () => {
-          if (thinkingSent) return;
-          thinkingSent = true;
-          runIdPromise = (async () => {
-            try {
-              const run = await client.createAgentRun(config.org_id, agentUserId, {
-                trigger_type: triggerType,
-                trigger_ref: triggerRef,
-                ...(opts.chatId ? { chat_id: opts.chatId } : {}),
-                ...(opts.defaultTargetType ? { default_target_type: opts.defaultTargetType, default_target_id: opts.defaultTargetId } : {}),
-              });
-              return run.id;
-            } catch (err) {
-              log?.warn(`pond[${accountId}]: failed to create agent run: ${String(err)}`);
-              return undefined;
-            }
-          })();
-          const state = getPondAccountState(accountId);
-          if (state) state.activeRuns.set(sessionKeyLower, runIdPromise);
+          // Generate a new group key per LLM response turn — shared across thinking + tool_call steps
+          turnGroupKey = crypto.randomUUID();
+          setDispatchGroupKey(sessionKey, turnGroupKey);
         },
       },
       replyOptions: {
@@ -179,12 +193,16 @@ async function dispatchToAgent(opts: {
           reasoningBuffer += payload.text ?? "";
         },
         onReasoningEnd: async () => {
-          const runId = runIdPromise ? await runIdPromise : undefined;
-          if (runId && reasoningBuffer) {
+          if (sessionId && reasoningBuffer) {
+            const targetType = opts.chatId ? "chat" : opts.defaultTargetType ?? "";
+            const targetId = opts.chatId ?? opts.defaultTargetId;
             try {
-              await client.createAgentStep(config.org_id, agentUserId, runId, {
+              await client.createAgentStep(config.org_id, agentUserId, sessionId, {
                 step_type: "thinking",
+                target_type: targetType,
+                target_id: targetId,
                 content: { text: reasoningBuffer },
+                group_key: turnGroupKey || undefined,
               });
             } catch (err) {
               log?.warn(`pond[${accountId}]: failed to create thinking step: ${String(err)}`);
@@ -420,7 +438,6 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
                 : `${fork.processedEvents.length} events in ${first.targetName ?? fork.targetId}`,
             },
             actions: [],
-            agentRunId: undefined,
           });
         }
         // Remove from tracking maps and clean up session files
@@ -489,6 +506,9 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
         chatId: event.targetId.startsWith("cht_") ? event.targetId : undefined,
         defaultTargetType: isTask ? "task" : undefined,
         defaultTargetId: isTask ? event.targetId : undefined,
+        senderId: event.senderId,
+        senderName: event.senderName,
+        messageBody: event.body,
         log,
       });
       if (!ok) throw new Error(`dispatch failed for ${event.messageId}`);
@@ -652,11 +672,25 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
         const count = await fetchAllChats(client, config.org_id, chatInfoMap);
         log?.info(`pond[${ctx.accountId}]: WebSocket connected, ${count} chats cached`);
 
+        // Create AgentSession on first hello (session lives across dispatches)
+        let activeSessionId: string | undefined;
+        try {
+          const session = await client.createAgentSession(config.org_id, agentUserId, {
+            runtime_type: "openclaw",
+            runtime_key: orchestratorKey,
+            runtime_ref: { hostname: os.hostname(), pid: process.pid },
+          });
+          activeSessionId = session.id;
+          log?.info(`pond[${ctx.accountId}]: created agent session ${session.id}`);
+        } catch (err) {
+          log?.warn(`pond[${ctx.accountId}]: failed to create agent session: ${String(err)}`);
+        }
+
         setPondAccountState(ctx.accountId, {
           client,
           orgId: config.org_id,
           agentUserId,
-          activeRuns: new Map(),
+          activeSessionId,
           wikiMountRoot,
           ws,
           orchestratorSessionKey: orchestratorKey,
@@ -1036,29 +1070,40 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     log?.info(`pond[${ctx.accountId}]: connecting to ${wsUrl}...`);
     await ws.connect();
 
-    // Clean up on abort
-    ctx.abortSignal.addEventListener("abort", () => {
-      if (heartbeatTimer) clearInterval(heartbeatTimer);
-      for (const [, dispatch] of activeDispatches) {
-        clearInterval(dispatch.typingTimer);
-      }
-      activeDispatches.clear();
-      stopWikiHelper?.();
-      ws.disconnect();
-      removePondAccountState(ctx.accountId);
-      for (const [key, value] of Object.entries(previousEnv)) {
-        if (value === undefined) {
-          delete process.env[key];
-        } else {
-          process.env[key] = value;
+    // Keep the gateway alive until aborted; clean up before resolving
+    return new Promise<void>((resolve) => {
+      ctx.abortSignal.addEventListener("abort", async () => {
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        for (const [, dispatch] of activeDispatches) {
+          clearInterval(dispatch.typingTimer);
         }
-      }
-      log?.info(`pond[${ctx.accountId}]: disconnected`);
-    });
+        activeDispatches.clear();
+        stopWikiHelper?.();
 
-    // Keep the gateway alive until aborted
-    return new Promise<void>((resolve) => {
-      ctx.abortSignal.addEventListener("abort", () => resolve());
+        // Complete the agent session
+        const currentState = getPondAccountState(ctx.accountId);
+        if (currentState?.activeSessionId) {
+          try {
+            await client.updateAgentSession(config.org_id, agentUserId, currentState.activeSessionId, {
+              status: "completed",
+            });
+          } catch (err) {
+            log?.warn(`pond[${ctx.accountId}]: failed to complete session: ${String(err)}`);
+          }
+        }
+
+        ws.disconnect();
+        removePondAccountState(ctx.accountId);
+        for (const [key, value] of Object.entries(previousEnv)) {
+          if (value === undefined) {
+            delete process.env[key];
+          } else {
+            process.env[key] = value;
+          }
+        }
+        log?.info(`pond[${ctx.accountId}]: disconnected`);
+        resolve();
+      });
     });
   },
 };

package/src/hooks.ts

@@ -1,16 +1,13 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { extractAccountIdFromSessionKey } from "./session.js";
-import { clearDispatchMessageId, clearSessionMessageId, getActiveRunId, getDispatchMessageId, getDispatchNoReply, getPondAccountState, getSessionChatId } from "./runtime.js";
+import { clearDispatchGroupKey, clearDispatchMessageId, clearSessionMessageId, getDispatchGroupKey, getDispatchMessageId, getDispatchNoReply, getPondAccountState, getSessionChatId } from "./runtime.js";
 
 /**
- * Resolve the PondClient + orgId + runId for a hook context.
- * Awaits the run ID promise so hooks that fire before createAgentRun
- * completes will block until the run ID is available (not silently drop).
+ * Resolve the PondClient + orgId + sessionId for a hook context.
+ * Returns undefined if the account/session is not active.
  */
-async function resolveClientForHook(sessionKey: string | undefined) {
+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.
   const chatId = getSessionChatId(sessionKey);
   if (!chatId) return undefined;
   const accountId = extractAccountIdFromSessionKey(sessionKey);
@@ -19,9 +16,7 @@ async function resolveClientForHook(sessionKey: string | undefined) {
   const state = getPondAccountState(accountId);
   if (!state) return undefined;
 
-  // 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 };
+  return { ...state, chatId, sessionId: state.activeSessionId };
 }
 
 const POND_CHANNEL_CONTEXT = `## Pond Channel — Message Delivery
@@ -46,17 +41,20 @@ export function registerPondHooks(api: OpenClawPluginApi) {
     return { appendSystemContext: POND_CHANNEL_CONTEXT };
   });
 
-  // before_tool_call -> (1) fire-and-forget step creation, (2) ENV injection for exec tool
+  // before_tool_call -> (1) await step creation to get step ID, (2) ENV injection for exec tool
   api.on("before_tool_call", async (event, ctx) => {
     const sessionKey = ctx.sessionKey;
 
-    // (1) Fire-and-forget step creation (all tools)
-    void (async () => {
-      const resolved = await resolveClientForHook(sessionKey);
-      if (!resolved || !resolved.activeRunId || !event.toolCallId) return;
+    // (1) Create tool_call step and await to get step ID
+    let stepId: string | undefined;
+    const resolved = resolveClientForHook(sessionKey);
+    if (resolved?.sessionId && event.toolCallId) {
+      const groupKey = sessionKey ? getDispatchGroupKey(sessionKey) : undefined;
       try {
-        await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
+        const step = await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.sessionId, {
           step_type: "tool_call",
+          target_type: resolved.chatId.startsWith("cht_") ? "chat" : resolved.chatId.startsWith("tsk_") ? "task" : "",
+          target_id: resolved.chatId || undefined,
           content: {
             call_id: event.toolCallId,
             tool_name: event.toolName,
@@ -64,11 +62,14 @@ export function registerPondHooks(api: OpenClawPluginApi) {
             status: "running",
             started_at: new Date().toISOString(),
           },
+          group_key: groupKey,
+          runtime_key: event.toolCallId,
         });
+        stepId = step.id;
       } catch (err) {
         log?.warn(`pond hook before_tool_call failed: ${String(err)}`);
       }
-    })();
+    }
 
     // (2) ENV injection — only for the exec (Bash) tool
     if (event.toolName !== "exec") return;
@@ -79,13 +80,13 @@ export function registerPondHooks(api: OpenClawPluginApi) {
     if (!state) return;
 
     // Dynamic per-dispatch context (changes each dispatch)
-    const runId = await getActiveRunId(state, sessionKey);
     const chatId = getSessionChatId(sessionKey);
     const triggerMsgId = getDispatchMessageId(sessionKey);
     const noReply = getDispatchNoReply(sessionKey);
 
     const injectedEnv: Record<string, string> = {};
-    if (runId) injectedEnv.POND_RUN_ID = runId;
+    if (state.activeSessionId) injectedEnv.POND_SESSION_ID = state.activeSessionId;
+    if (stepId) injectedEnv.POND_STEP_ID = stepId;
     if (chatId) injectedEnv.POND_CHAT_ID = chatId;
     if (triggerMsgId) injectedEnv.POND_TRIGGER_MESSAGE_ID = triggerMsgId;
     if (noReply) injectedEnv.POND_NO_REPLY = "1";
@@ -105,13 +106,15 @@ export function registerPondHooks(api: OpenClawPluginApi) {
     };
   });
 
-  // after_tool_call -> send tool_result step to AgentRun
+  // after_tool_call -> send tool_result step to AgentSession
   api.on("after_tool_call", async (event, ctx) => {
-    const resolved = await resolveClientForHook(ctx.sessionKey);
-    if (!resolved || !resolved.activeRunId || !event.toolCallId) return;
+    const resolved = resolveClientForHook(ctx.sessionKey);
+    if (!resolved?.sessionId || !event.toolCallId) return;
     try {
-      await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
+      await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.sessionId, {
         step_type: "tool_result",
+        target_type: resolved.chatId.startsWith("cht_") ? "chat" : resolved.chatId.startsWith("tsk_") ? "task" : "",
+        target_id: resolved.chatId || undefined,
         content: {
           call_id: event.toolCallId,
           tool_name: event.toolName,
@@ -126,31 +129,35 @@ export function registerPondHooks(api: OpenClawPluginApi) {
     }
   });
 
-  // agent_end -> complete the AgentRun
-  api.on("agent_end", async (_event, ctx) => {
-    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",
-      });
-    } 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 (ctx.sessionKey) {
-        clearSessionMessageId(ctx.sessionKey);
-        clearDispatchMessageId(ctx.sessionKey);
-      }
-      if (state && ctx.sessionKey) {
-        state.activeRuns.delete(ctx.sessionKey.toLowerCase());
+  // agent_end -> end of a dispatch cycle, NOT end of session.
+  // Session lives across dispatches — don't update session status here.
+  // On error: emit a visible error step so the chat user sees the failure.
+  api.on("agent_end", async (event, ctx) => {
+    // Emit error step if the dispatch failed
+    if (event.error && ctx.sessionKey) {
+      const accountId = extractAccountIdFromSessionKey(ctx.sessionKey);
+      const state = accountId ? getPondAccountState(accountId) : undefined;
+      const chatId = getSessionChatId(ctx.sessionKey);
+      if (state?.activeSessionId && chatId) {
+        try {
+          await state.client.createAgentStep(state.orgId, state.agentUserId, state.activeSessionId, {
+            step_type: "text",
+            target_type: "chat",
+            target_id: chatId,
+            content: { text: `Dispatch failed: ${String(event.error)}`, suppressed: false },
+            projection: true,
+          });
+        } catch (err) {
+          log?.warn(`pond hook agent_end: failed to emit error step: ${String(err)}`);
+        }
       }
     }
+
+    // Clean up dispatch-specific state
+    if (ctx.sessionKey) {
+      clearSessionMessageId(ctx.sessionKey);
+      clearDispatchMessageId(ctx.sessionKey);
+      clearDispatchGroupKey(ctx.sessionKey);
+    }
   });
 }

package/src/outbound.ts

@@ -3,7 +3,7 @@ import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 /** Extract ChannelOutboundAdapter from ChannelPlugin (removed from public SDK exports in 2026.3.24). */
 type ChannelOutboundAdapter = NonNullable<ChannelPlugin["outbound"]>;
 import { resolvePondAccount } from "./accounts.js";
-import { getPondAccountState, getSessionChatId } from "./runtime.js";
+import { getPondAccountState } from "./runtime.js";
 import { PondClient } from "@pnds/sdk";
 import type { SendMessageRequest } from "@pnds/sdk";
 
@@ -25,21 +25,11 @@ 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;
-        }
-      }
-    }
-
+    // Outbound path has no step context — send without agent_step_id.
+    // Step linkage happens via the CLI's ENV-injected POND_STEP_ID in the normal dispatch path.
     const req: SendMessageRequest = {
       message_type: "text",
       content: { text },
-      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,21 +19,12 @@ export type PondAccountState = {
   client: PondClient;
   orgId: string;
   agentUserId: string;
-  activeRuns: Map<string, Promise<string | undefined>>; // sessionKey (lowercased) → runId promise
+  activeSessionId?: string;
   wikiMountRoot?: string;
   ws?: PondWs;
   orchestratorSessionKey?: string;
 };
 
-/** 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) {
@@ -94,6 +85,22 @@ export function clearDispatchMessageId(sessionKey: string) {
   dispatchMessageIdMap.delete(sessionKey.toLowerCase());
 }
 
+// Per-dispatch group key — shared between thinking + tool_call steps for Session Panel grouping.
+// Set per LLM response turn in gateway.ts, read in hooks.ts.
+const dispatchGroupKeyMap = new Map<string, string>();
+
+export function setDispatchGroupKey(sessionKey: string, groupKey: string) {
+  dispatchGroupKeyMap.set(sessionKey.toLowerCase(), groupKey);
+}
+
+export function getDispatchGroupKey(sessionKey: string): string | undefined {
+  return dispatchGroupKeyMap.get(sessionKey.toLowerCase());
+}
+
+export function clearDispatchGroupKey(sessionKey: string) {
+  dispatchGroupKeyMap.delete(sessionKey.toLowerCase());
+}
+
 // Per-dispatch noReply flag — deterministic suppression for agent-to-agent loop prevention.
 // Injected as POND_NO_REPLY=1 into Bash env; the CLI checks and suppresses sends.
 const dispatchNoReplyMap = new Map<string, boolean>();
@@ -115,7 +122,6 @@ export type ForkResult = {
   forkSessionKey: string;
   sourceEvent: { type: string; targetId: string; summary: string };
   actions: string[];  // human-readable list of actions taken (e.g. "replied to cht_xxx")
-  agentRunId?: string;
 };
 
 /** Mutable dispatch state for the orchestrator gateway. Per-account, managed by gateway.ts. */