@pnds/pond 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnds/pond",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenClaw channel plugin for Pond IM",
   "license": "MIT",
   "repository": {

package/src/channel.ts

@@ -20,7 +20,7 @@ export const pondPlugin: ChannelPlugin<ResolvedPondAccount> = {
     chatTypes: ["direct", "group"],
     polls: false,
     threads: false,
-    media: false,
+    media: true,
     reactions: false,
     edit: false,
     reply: false,

package/src/config-manager.ts

@@ -0,0 +1,150 @@
+import type { PondClient } from "@pnds/sdk";
+import type { PlatformConfigResponse } from "@pnds/sdk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface CachedPlatformConfig {
+  version: string;
+  config: Record<string, unknown>;
+  fetchedAt: string;
+}
+
+interface ConfigManagerOpts {
+  client: PondClient;
+  stateDir: string;
+  configPath: string;
+  credentials: { api_key: string; pond_url: string };
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+const CACHE_FILENAME = "pond-platform-config.json";
+
+function cachePath(stateDir: string): string {
+  return path.join(stateDir, CACHE_FILENAME);
+}
+
+function loadCachedConfig(stateDir: string): CachedPlatformConfig | null {
+  try {
+    const raw = fs.readFileSync(cachePath(stateDir), "utf-8");
+    return JSON.parse(raw) as CachedPlatformConfig;
+  } catch {
+    return null;
+  }
+}
+
+function saveCachedConfig(stateDir: string, config: PlatformConfigResponse): void {
+  const cached: CachedPlatformConfig = {
+    version: config.version,
+    config: config.config,
+    fetchedAt: new Date().toISOString(),
+  };
+  const filePath = cachePath(stateDir);
+  const tmpPath = `${filePath}.tmp`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(tmpPath, JSON.stringify(cached, null, 2), "utf-8");
+  fs.renameSync(tmpPath, filePath);
+}
+
+/**
+ * Deep-merge platform config into an existing openclaw.json file.
+ * Only overwrites `models.providers.pond` and `agents.defaults` sections;
+ * all other keys (user customizations, other providers) are preserved.
+ */
+function applyToOpenClawConfig(
+  configPath: string,
+  platformConfig: Record<string, unknown>,
+  credentials: { api_key: string; pond_url: string },
+): void {
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    existing = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    // File doesn't exist or is invalid — start fresh
+  }
+
+  // Deep-merge models.providers.pond (preserve existing fields, overlay platform, inject credentials)
+  const models = (existing.models ?? {}) as Record<string, unknown>;
+  const providers = (models.providers ?? {}) as Record<string, unknown>;
+  const existingPond = (providers.pond ?? {}) as Record<string, unknown>;
+  const platformModels = (platformConfig.models ?? {}) as Record<string, unknown>;
+  const platformProviders = (platformModels.providers ?? {}) as Record<string, unknown>;
+  const platformPond = (platformProviders.pond ?? {}) as Record<string, unknown>;
+
+  providers.pond = {
+    ...existingPond,
+    ...platformPond,
+    apiKey: credentials.api_key,
+  };
+  models.providers = providers;
+  existing.models = models;
+
+  // Deep-merge agents.defaults (preserve existing fields, overlay platform)
+  const platformAgents = (platformConfig.agents ?? {}) as Record<string, unknown>;
+  if (platformAgents.defaults !== undefined) {
+    const agents = (existing.agents ?? {}) as Record<string, unknown>;
+    const existingDefaults = (agents.defaults ?? {}) as Record<string, unknown>;
+    agents.defaults = {
+      ...existingDefaults,
+      ...(platformAgents.defaults as Record<string, unknown>),
+    };
+    existing.agents = agents;
+  }
+
+  // Atomic write
+  const tmpPath = `${configPath}.tmp`;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(tmpPath, JSON.stringify(existing, null, 2), "utf-8");
+  fs.renameSync(tmpPath, configPath);
+}
+
+/**
+ * Fetch platform config from the server, cache it (LKG), and apply to openclaw.json.
+ * Degrades gracefully: uses cached config on fetch failure, continues if neither is available.
+ */
+export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Promise<void> {
+  const { client, stateDir, configPath, credentials, log } = opts;
+
+  // 1. Load cached config (LKG)
+  const cached = loadCachedConfig(stateDir);
+
+  // 2. Fetch from server (with version for 304)
+  let fresh: PlatformConfigResponse | null = null;
+  try {
+    fresh = await client.getPlatformConfig(cached?.version);
+  } catch (err) {
+    // Fetch failed — fall through to use cache
+    if (cached) {
+      log?.warn(`platform config fetch failed, using cached version ${cached.version}: ${String(err)}`);
+      applyToOpenClawConfig(configPath, cached.config, credentials);
+      return;
+    }
+    // No cache and fetch fails — degrade gracefully
+    log?.error(`platform config fetch failed and no cache available: ${String(err)}`);
+    return;
+  }
+
+  // 3. 304 — config unchanged
+  if (fresh === null) {
+    log?.info("platform config unchanged (304)");
+    if (cached) {
+      applyToOpenClawConfig(configPath, cached.config, credentials);
+    }
+    return;
+  }
+
+  // 4. Validate schema compatibility before accepting
+  const SUPPORTED_SCHEMA_VERSION = 1;
+  if (fresh.schema_version !== undefined && fresh.schema_version > SUPPORTED_SCHEMA_VERSION) {
+    log?.error(`platform config schema_version ${fresh.schema_version} is newer than supported (${SUPPORTED_SCHEMA_VERSION}), keeping current config`);
+    if (cached) {
+      applyToOpenClawConfig(configPath, cached.config, credentials);
+    }
+    return;
+  }
+
+  // 5. Newer config received — save cache and apply
+  log?.info(`platform config updated to version ${fresh.version}`);
+  saveCachedConfig(stateDir, fresh);
+  applyToOpenClawConfig(configPath, fresh.config, credentials);
+}

package/src/gateway.ts

@@ -1,11 +1,14 @@
-import type { ChannelGatewayAdapter } from "openclaw/plugin-sdk";
+import type { ChannelGatewayAdapter, PluginRuntime } from "openclaw/plugin-sdk";
 import { PondClient, PondWs, MENTION_ALL_USER_ID, WS_EVENTS } from "@pnds/sdk";
-import type { Chat, MessageNewData, SendMessageRequest, TextContent, HelloData, ChatUpdateData } from "@pnds/sdk";
+import type { Chat, MessageNewData, TextContent, MediaContent, HelloData, ChatUpdateData, AgentConfigUpdateData } from "@pnds/sdk";
+import type { PondChannelConfig } from "./types.js";
 import * as os from "node:os";
+import * as path from "node:path";
 import { resolvePondAccount } from "./accounts.js";
-import { getPondRuntime, setPondAccountState, removePondAccountState, setSessionChatId } from "./runtime.js";
+import { getPondRuntime, setPondAccountState, getPondAccountState, removePondAccountState, setSessionChatId } from "./runtime.js";
 import { buildSessionKey } from "./session.js";
 import type { ResolvedPondAccount } from "./types.js";
+import { fetchAndApplyPlatformConfig } from "./config-manager.js";
 
 function resolveWsUrl(account: ResolvedPondAccount): string {
   if (account.config.ws_url) return account.config.ws_url;
@@ -35,6 +38,65 @@ async function fetchAllChats(
   return total;
 }
 
+/**
+ * Dispatch an inbound message to the OpenClaw agent and handle the reply.
+ * Shared by both text and file message handlers to avoid duplication.
+ */
+async function dispatchToAgent(opts: {
+  core: PluginRuntime;
+  cfg: Record<string, unknown>;
+  client: PondClient;
+  config: PondChannelConfig;
+  agentUserId: string;
+  accountId: string;
+  chatId: string;
+  messageId: string;
+  inboundCtx: Record<string, unknown>;
+  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;
+  let thinkingSent = false;
+  try {
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: inboundCtx,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload: { text?: string }) => {
+          const replyText = payload.text?.trim();
+          if (!replyText) return;
+          await client.sendMessage(config.org_id, chatId, {
+            message_type: "text",
+            content: { text: replyText },
+          });
+        },
+        onReplyStart: () => {
+          if (thinkingSent) return;
+          thinkingSent = true;
+          (async () => {
+            try {
+              const run = await client.createAgentRun(config.org_id, agentUserId, {
+                trigger_type: "mention",
+                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: "" },
+              });
+            } catch (err) {
+              log?.warn(`pond[${accountId}]: failed to create agent run: ${String(err)}`);
+            }
+          })();
+        },
+      },
+    });
+  } catch (err) {
+    log?.error(`pond[${accountId}]: dispatch failed for ${messageId}: ${String(err)}`);
+  }
+}
+
 export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
   startAccount: async (ctx) => {
     const account = resolvePondAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
@@ -55,6 +117,30 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     const agentUserId = me.id;
     log?.info(`pond[${ctx.accountId}]: authenticated as ${me.display_name} (${agentUserId})`);
 
+    // Inject env vars so child processes (e.g. @pnds/cli) inherit Pond credentials
+    process.env.POND_API_URL = config.pond_url;
+    process.env.POND_API_KEY = config.api_key;
+    process.env.POND_ORG_ID = config.org_id;
+
+    // Apply platform config (models, defaults)
+    // Use OPENCLAW_STATE_DIR if set, otherwise derive from HOME (systemd sets HOME=/data for hosted agents)
+    const stateDir = process.env.OPENCLAW_STATE_DIR
+      || path.join(process.env.HOME || "/data", ".openclaw");
+    const openclawConfigPath = path.join(stateDir, "openclaw.json");
+    const configManagerOpts = {
+      client,
+      stateDir,
+      configPath: openclawConfigPath,
+      credentials: { api_key: config.api_key, pond_url: config.pond_url },
+      log,
+    };
+
+    try {
+      await fetchAndApplyPlatformConfig(configManagerOpts);
+    } catch (err) {
+      log?.warn(`pond[${ctx.accountId}]: platform config fetch failed: ${String(err)}`);
+    }
+
     // Connect WebSocket via ticket auth (reconnection enabled by default in PondWs)
     const wsUrl = resolveWsUrl(account);
     const ws = new PondWs({
@@ -67,15 +153,18 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
 
     // Session ID from hello — used for heartbeat
     let sessionId = "";
+    // Heartbeat interval handle — created inside hello handler with server-provided interval
+    let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 
     // Log connection state changes (covers reconnection)
     ws.onStateChange((state) => {
       log?.info(`pond[${ctx.accountId}]: connection state → ${state}`);
     });
 
-    // On hello, cache chat types (with pagination) and start heartbeat
+    // On hello, cache chat types and start heartbeat with server-provided interval
     ws.on("hello", async (data: HelloData) => {
       sessionId = data.session_id ?? "";
+      const intervalSec = data.heartbeat_interval > 0 ? data.heartbeat_interval : 30;
       try {
         const count = await fetchAllChats(client, config.org_id, chatTypeMap);
         log?.info(`pond[${ctx.accountId}]: WebSocket connected, ${count} chats cached`);
@@ -86,6 +175,19 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
           orgId: config.org_id,
           agentUserId,
         });
+
+        // (Re)start heartbeat with server-provided interval
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        heartbeatTimer = setInterval(() => {
+          if (ws.state !== "connected") return;
+          ws.sendAgentHeartbeat(sessionId, {
+            hostname: os.hostname(),
+            cores: os.cpus().length,
+            mem_total: os.totalmem(),
+            mem_free: os.freemem(),
+            uptime: os.uptime(),
+          });
+        }, intervalSec * 1000);
       } catch (err) {
         log?.error(`pond[${ctx.accountId}]: failed to fetch chats: ${String(err)}`);
       }
@@ -98,14 +200,10 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       }
     });
 
-    // Handle inbound messages
+    // Handle inbound messages (text + file)
     ws.on("message.new", async (data: MessageNewData) => {
       if (data.sender_id === agentUserId) return;
-      if (data.message_type !== "text") return;
-
-      const content = data.content as TextContent;
-      const text = content.text?.trim();
-      if (!text) return;
+      if (data.message_type !== "text" && data.message_type !== "file") return;
 
       const chatId = data.chat_id;
 
@@ -122,13 +220,46 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
         }
       }
 
-      // In group chats, only respond when @mentioned or @all
-      if (chatType === "group") {
-        const mentions = content.mentions ?? [];
-        const isMentioned = mentions.some(
-          (m) => m.user_id === agentUserId || m.user_id === MENTION_ALL_USER_ID
-        );
-        if (!isMentioned) return;
+      // Build body text and optional media fields based on message type
+      let body = "";
+      let mediaFields: Record<string, string | undefined> = {};
+
+      if (data.message_type === "text") {
+        const content = data.content as TextContent;
+        body = content.text?.trim() ?? "";
+        if (!body) return;
+
+        // In group chats, only respond when @mentioned or @all
+        if (chatType === "group") {
+          const mentions = content.mentions ?? [];
+          const isMentioned = mentions.some(
+            (m) => m.user_id === agentUserId || m.user_id === MENTION_ALL_USER_ID
+          );
+          if (!isMentioned) return;
+        }
+      } else {
+        // file message
+        const content = data.content as MediaContent;
+
+        // In group chats, file messages have no mentions field — skip
+        if (chatType === "group") return;
+
+        body = content.caption?.trim()
+          || `[file: ${content.file_name || "attachment"}]`;
+
+        // Resolve presigned download URL for the attachment
+        if (content.attachment_id) {
+          try {
+            const fileRes = await client.getFileUrl(content.attachment_id);
+            mediaFields = {
+              MediaUrl: fileRes.url,
+              MediaType: content.mime_type,
+            };
+          } catch (err) {
+            log?.warn(`pond[${ctx.accountId}]: failed to get file URL for ${content.attachment_id}: ${String(err)}`);
+            // Degrade gracefully — agent still gets the body text
+          }
+        }
       }
 
       const sessionKey = buildSessionKey(ctx.accountId, chatType, chatId);
@@ -136,10 +267,11 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
 
       // Build inbound context for OpenClaw agent
       const inboundCtx = core.channel.reply.finalizeInboundContext({
-        Body: text,
-        BodyForAgent: text,
-        RawBody: text,
-        CommandBody: text,
+        Body: body,
+        BodyForAgent: body,
+        RawBody: body,
+        CommandBody: body,
+        ...mediaFields,
         From: `pond:${data.sender_id}`,
         To: `pond:${chatId}`,
         SessionKey: sessionKey,
@@ -156,60 +288,42 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
         OriginatingTo: `pond:${chatId}`,
       });
 
-      let thinkingSent = false;
+      await dispatchToAgent({
+        core,
+        cfg: ctx.cfg,
+        client,
+        config,
+        agentUserId,
+        accountId: ctx.accountId,
+        chatId,
+        messageId: data.id,
+        inboundCtx,
+        log,
+      });
+    });
+
+    // Re-apply platform config when server pushes an update notification
+    ws.on("agent_config.update", async (data: AgentConfigUpdateData) => {
+      log?.info(`pond[${ctx.accountId}]: config update notification (version=${data.version})`);
       try {
-        await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-          ctx: inboundCtx,
-          cfg: ctx.cfg,
-          dispatcherOptions: {
-            deliver: async (payload) => {
-              const replyText = payload.text?.trim();
-              if (!replyText) return;
-              await client.sendMessage(config.org_id, chatId, {
-                message_type: "text",
-                content: { text: replyText },
-              });
-            },
-            onReplyStart: () => {
-              if (thinkingSent) return;
-              thinkingSent = true;
-              // Send "thinking" state delta (fire-and-forget)
-              client.sendMessage(config.org_id, chatId, {
-                message_type: "state_delta",
-                content: { state: "thinking", text: "", progress: 0, collapsible: true },
-              } as SendMessageRequest).catch((err) => {
-                log?.warn(`pond[${ctx.accountId}]: failed to send thinking state: ${String(err)}`);
-              });
-            },
-          },
-        });
+        await fetchAndApplyPlatformConfig(configManagerOpts);
       } catch (err) {
-        log?.error(`pond[${ctx.accountId}]: dispatch failed for ${data.id}: ${String(err)}`);
+        log?.warn(`pond[${ctx.accountId}]: config update failed: ${String(err)}`);
       }
     });
 
     log?.info(`pond[${ctx.accountId}]: connecting to ${wsUrl}...`);
     await ws.connect();
 
-    // Start periodic heartbeat with system telemetry
-    const heartbeatInterval = setInterval(() => {
-      if (ws.state !== "connected") return;
-      const totalMem = os.totalmem();
-      const freeMem = os.freemem();
-      ws.sendAgentHeartbeat(sessionId, {
-        hostname: os.hostname(),
-        cores: os.cpus().length,
-        mem_total: totalMem,
-        mem_free: freeMem,
-        uptime: os.uptime(),
-      });
-    }, 30_000); // every 30s
-
     // Clean up on abort
     ctx.abortSignal.addEventListener("abort", () => {
-      clearInterval(heartbeatInterval);
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
       ws.disconnect();
       removePondAccountState(ctx.accountId);
+      // Clear injected env vars so stale credentials don't leak to future subprocesses
+      delete process.env.POND_API_URL;
+      delete process.env.POND_API_KEY;
+      delete process.env.POND_ORG_ID;
       log?.info(`pond[${ctx.accountId}]: disconnected`);
     });
 

package/src/hooks.ts

@@ -1,10 +1,9 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import type { SendMessageRequest } from "@pnds/sdk";
 import { extractAccountIdFromSessionKey } from "./session.js";
 import { getPondAccountState, getSessionChatId } from "./runtime.js";
 
 /**
- * Resolve the PondClient + orgId for a hook context.
+ * Resolve the PondClient + orgId + runId for a hook context.
  * Matches by accountId extracted from the session key.
  */
 function resolveClientForHook(sessionKey: string | undefined) {
@@ -21,36 +20,59 @@ function resolveClientForHook(sessionKey: string | undefined) {
   return { ...state, chatId };
 }
 
+const POND_CLI_CONTEXT = `## Pond CLI
+
+You have access to the Pond platform via the \`@pnds/cli\` CLI. Auth is pre-configured — just run commands directly.
+
+\`\`\`
+npx @pnds/cli@latest whoami                          # Check your identity
+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 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
+npx @pnds/cli@latest projects list                   # List projects
+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.`;
+
 export function registerPondHooks(api: OpenClawPluginApi) {
   const log = api.logger;
 
-  // before_tool_call -> send tool_call message to Pond
+  // Inject CLI awareness into agent system prompt
+  api.on("before_prompt_build", () => {
+    return { prependContext: POND_CLI_CONTEXT };
+  });
+
+  // before_tool_call -> send tool_call step to AgentRun
   api.on("before_tool_call", async (event, ctx) => {
     const resolved = resolveClientForHook(ctx.sessionKey);
-    if (!resolved) return;
+    if (!resolved || !resolved.activeRunId) return;
     try {
-      const req: SendMessageRequest = {
-        message_type: "tool_call",
+      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(),
         },
-      };
-      await resolved.client.sendMessage(resolved.orgId, resolved.chatId, req);
+      });
     } catch (err) {
       log?.warn(`pond hook before_tool_call failed: ${String(err)}`);
     }
   });
 
-  // after_tool_call -> send tool_result message to Pond
+  // after_tool_call -> send tool_result step to AgentRun
   api.on("after_tool_call", async (event, ctx) => {
     const resolved = resolveClientForHook(ctx.sessionKey);
-    if (!resolved) return;
+    if (!resolved || !resolved.activeRunId) return;
     try {
-      const req: SendMessageRequest = {
-        message_type: "tool_result",
+      await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
+        step_type: "tool_result",
         content: {
           tool_call_id: event.toolCallId ?? "",
           tool_name: event.toolName,
@@ -59,31 +81,29 @@ export function registerPondHooks(api: OpenClawPluginApi) {
           duration_ms: event.durationMs ?? 0,
           collapsible: true,
         },
-      };
-      await resolved.client.sendMessage(resolved.orgId, resolved.chatId, req);
+      });
     } catch (err) {
       log?.warn(`pond hook after_tool_call failed: ${String(err)}`);
     }
   });
 
-  // agent_end -> send state_delta completed
+  // agent_end -> complete the AgentRun
   api.on("agent_end", async (_event, ctx) => {
     const resolved = resolveClientForHook(ctx.sessionKey);
     if (!resolved) {
       log?.warn(`pond hook agent_end: could not resolve client (sessionKey=${ctx.sessionKey})`);
       return;
     }
+    if (!resolved.activeRunId) return;
     try {
-      const req: SendMessageRequest = {
-        message_type: "state_delta",
-        content: {
-          state: "completed",
-          text: "",
-          progress: 100,
-          collapsible: true,
-        },
-      };
-      await resolved.client.sendMessage(resolved.orgId, resolved.chatId, req);
+      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)}`);
     }

package/src/runtime.ts

@@ -19,6 +19,7 @@ export type PondAccountState = {
   client: PondClient;
   orgId: string;
   agentUserId: string;
+  activeRunId?: string; // current AgentRun ID, set by gateway on reply start
 };
 
 const accountStates = new Map<string, PondAccountState>();