@pnds/pond 1.8.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnds/pond",
-  "version": "1.8.0",
+  "version": "1.10.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.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)}`);
@@ -402,7 +420,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);
         }
@@ -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}`);
@@ -535,10 +555,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 +570,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);
@@ -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,
@@ -683,13 +717,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 +791,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 +836,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 +895,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 +905,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 +949,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 +1033,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,46 +1053,57 @@ 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)`);
       }
     }
 
     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. */