@pnds/pond 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,26 @@
+{
+  "id": "pond",
+  "channels": ["pond"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["pond_url", "api_key", "org_id"],
+    "properties": {
+      "pond_url": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Pond API base URL"
+      },
+      "api_key": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Agent API key (agk_xxx)"
+      },
+      "org_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Organisation ID"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@pnds/pond",
+  "version": "0.1.0",
+  "description": "OpenClaw channel plugin for Pond IM",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RFlowAI/pond",
+    "directory": "ts/openclaw-channel"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "dependencies": {
+    "@pnds/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,38 @@
+import type { ResolvedPondAccount, PondChannelConfig } from "./types.js";
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+type OpenClawConfig = Record<string, unknown>;
+
+function readPondConfig(cfg: OpenClawConfig): PondChannelConfig | undefined {
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  return channels?.pond as PondChannelConfig | undefined;
+}
+
+export function listPondAccountIds(cfg: OpenClawConfig): string[] {
+  const pondCfg = readPondConfig(cfg);
+  if (!pondCfg) return [];
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolvePondAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+}): ResolvedPondAccount {
+  const { cfg, accountId = DEFAULT_ACCOUNT_ID } = params;
+  const pondCfg = readPondConfig(cfg);
+  const config: PondChannelConfig = {
+    pond_url: pondCfg?.pond_url ?? "",
+    api_key: pondCfg?.api_key ?? "",
+    org_id: pondCfg?.org_id ?? "",
+    ws_url: pondCfg?.ws_url,
+    enabled: pondCfg?.enabled,
+  };
+  const configured = Boolean(config.api_key && config.pond_url && config.org_id);
+  return {
+    accountId,
+    enabled: config.enabled !== false,
+    configured,
+    config,
+  };
+}

package/src/channel.ts

@@ -0,0 +1,40 @@
+import type { ChannelPlugin, ChannelMeta } from "openclaw/plugin-sdk";
+import { listPondAccountIds, resolvePondAccount } from "./accounts.js";
+import { pondGateway } from "./gateway.js";
+import { pondOutbound } from "./outbound.js";
+import type { ResolvedPondAccount } from "./types.js";
+
+const meta: ChannelMeta = {
+  id: "pond",
+  label: "Pond",
+  selectionLabel: "Pond IM",
+  docsPath: "/channels/pond",
+  blurb: "Agent-Native IM platform.",
+  order: 80,
+};
+
+export const pondPlugin: ChannelPlugin<ResolvedPondAccount> = {
+  id: "pond",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    polls: false,
+    threads: false,
+    media: false,
+    reactions: false,
+    edit: false,
+    reply: false,
+  },
+  config: {
+    listAccountIds: (cfg) => listPondAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolvePondAccount({ cfg, accountId: accountId ?? undefined }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+  },
+  outbound: pondOutbound,
+  gateway: pondGateway,
+};

package/src/gateway.ts

@@ -0,0 +1,221 @@
+import type { ChannelGatewayAdapter } 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 * as os from "node:os";
+import { resolvePondAccount } from "./accounts.js";
+import { getPondRuntime, setPondAccountState, removePondAccountState, setSessionChatId } from "./runtime.js";
+import { buildSessionKey } from "./session.js";
+import type { ResolvedPondAccount } from "./types.js";
+
+function resolveWsUrl(account: ResolvedPondAccount): string {
+  if (account.config.ws_url) return account.config.ws_url;
+  const base = account.config.pond_url.replace(/\/$/, "");
+  const wsBase = base.replace(/^http/, "ws");
+  return `${wsBase}/ws`;
+}
+
+/**
+ * Fetch all chats with pagination and populate the type map.
+ */
+async function fetchAllChats(
+  client: PondClient,
+  orgId: string,
+  chatTypeMap: Map<string, Chat["type"]>,
+): Promise<number> {
+  let cursor: string | undefined;
+  let total = 0;
+  do {
+    const res = await client.getChats(orgId, { limit: 100, cursor });
+    for (const c of res.data) {
+      chatTypeMap.set(c.id, c.type);
+    }
+    total += res.data.length;
+    cursor = res.has_more ? res.next_cursor : undefined;
+  } while (cursor);
+  return total;
+}
+
+export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
+  startAccount: async (ctx) => {
+    const account = resolvePondAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
+    if (!account.enabled) return;
+    if (!account.configured) throw new Error("Pond account is not configured: pond_url/api_key/org_id required");
+
+    const { config } = account;
+    const core = getPondRuntime();
+    const log = ctx.log;
+
+    const client = new PondClient({
+      baseUrl: config.pond_url,
+      token: config.api_key,
+    });
+
+    // Resolve agent's own user ID
+    const me = await client.getMe();
+    const agentUserId = me.id;
+    log?.info(`pond[${ctx.accountId}]: authenticated as ${me.display_name} (${agentUserId})`);
+
+    // Connect WebSocket via ticket auth (reconnection enabled by default in PondWs)
+    const wsUrl = resolveWsUrl(account);
+    const ws = new PondWs({
+      getTicket: () => client.getWsTicket(),
+      wsUrl,
+    });
+
+    // Chat type lookup — populated on hello, used by message handler
+    const chatTypeMap = new Map<string, Chat["type"]>();
+
+    // Session ID from hello — used for heartbeat
+    let sessionId = "";
+
+    // 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
+    ws.on("hello", async (data: HelloData) => {
+      sessionId = data.session_id ?? "";
+      try {
+        const count = await fetchAllChats(client, config.org_id, chatTypeMap);
+        log?.info(`pond[${ctx.accountId}]: WebSocket connected, ${count} chats cached`);
+
+        // Cache client state only after successful connection
+        setPondAccountState(ctx.accountId, {
+          client,
+          orgId: config.org_id,
+          agentUserId,
+        });
+      } catch (err) {
+        log?.error(`pond[${ctx.accountId}]: failed to fetch chats: ${String(err)}`);
+      }
+    });
+
+    // 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"]);
+      }
+    });
+
+    // Handle inbound messages
+    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;
+
+      const chatId = data.chat_id;
+
+      // Resolve chat type — query API for unknown chats
+      let chatType = chatTypeMap.get(chatId);
+      if (!chatType) {
+        try {
+          const chat = await client.getChat(config.org_id, chatId);
+          chatType = chat.type;
+          chatTypeMap.set(chatId, chatType);
+        } catch (err) {
+          log?.warn(`pond[${ctx.accountId}]: failed to resolve chat type for ${chatId}, skipping message: ${String(err)}`);
+          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;
+      }
+
+      const sessionKey = buildSessionKey(ctx.accountId, chatType, chatId);
+      setSessionChatId(sessionKey, chatId);
+
+      // Build inbound context for OpenClaw agent
+      const inboundCtx = core.channel.reply.finalizeInboundContext({
+        Body: text,
+        BodyForAgent: text,
+        RawBody: text,
+        CommandBody: text,
+        From: `pond:${data.sender_id}`,
+        To: `pond:${chatId}`,
+        SessionKey: sessionKey,
+        AccountId: ctx.accountId,
+        ChatType: chatType,
+        SenderName: data.sender?.display_name ?? data.sender_id,
+        SenderId: data.sender_id,
+        Provider: "pond" as const,
+        Surface: "pond" as const,
+        MessageSid: data.id,
+        Timestamp: Date.now(),
+        CommandAuthorized: true,
+        OriginatingChannel: "pond" as const,
+        OriginatingTo: `pond:${chatId}`,
+      });
+
+      let thinkingSent = false;
+      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)}`);
+              });
+            },
+          },
+        });
+      } catch (err) {
+        log?.error(`pond[${ctx.accountId}]: dispatch failed for ${data.id}: ${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);
+      ws.disconnect();
+      removePondAccountState(ctx.accountId);
+      log?.info(`pond[${ctx.accountId}]: disconnected`);
+    });
+
+    // Keep the gateway alive until aborted
+    return new Promise<void>((resolve) => {
+      ctx.abortSignal.addEventListener("abort", () => resolve());
+    });
+  },
+};

package/src/hooks.ts

@@ -0,0 +1,91 @@
+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.
+ * Matches by accountId extracted from the session key.
+ */
+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);
+  if (!accountId) return undefined;
+
+  const state = getPondAccountState(accountId);
+  if (!state) return undefined;
+  return { ...state, chatId };
+}
+
+export function registerPondHooks(api: OpenClawPluginApi) {
+  const log = api.logger;
+
+  // before_tool_call -> send tool_call message to Pond
+  api.on("before_tool_call", async (event, ctx) => {
+    const resolved = resolveClientForHook(ctx.sessionKey);
+    if (!resolved) return;
+    try {
+      const req: SendMessageRequest = {
+        message_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
+  api.on("after_tool_call", async (event, ctx) => {
+    const resolved = resolveClientForHook(ctx.sessionKey);
+    if (!resolved) return;
+    try {
+      const req: SendMessageRequest = {
+        message_type: "tool_result",
+        content: {
+          tool_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 ?? "")),
+          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
+  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;
+    }
+    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);
+    } catch (err) {
+      log?.warn(`pond hook agent_end failed: ${String(err)}`);
+    }
+  });
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { pondPlugin } from "./channel.js";
+import { setPondRuntime } from "./runtime.js";
+import { registerPondHooks } from "./hooks.js";
+
+const plugin = {
+  id: "pond",
+  name: "Pond",
+  description: "Pond IM channel plugin — Agent-Native messaging with tool call visualization.",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setPondRuntime(api.runtime);
+    api.registerChannel({ plugin: pondPlugin });
+    registerPondHooks(api);
+  },
+};
+
+export default plugin;

package/src/outbound.ts

@@ -0,0 +1,32 @@
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
+import { resolvePondAccount } from "./accounts.js";
+import { getPondAccountState } from "./runtime.js";
+import { PondClient } from "@pnds/sdk";
+import type { SendMessageRequest } from "@pnds/sdk";
+
+export const pondOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  textChunkLimit: 10000,
+  chunker: null,
+
+  sendText: async ({ cfg, to, text, accountId }) => {
+    const account = resolvePondAccount({ cfg, accountId: accountId ?? undefined });
+    if (!account.enabled) throw new Error("Pond account is disabled");
+    if (!account.configured) throw new Error("Pond account is not configured: pond_url/api_key/org_id required");
+
+    const state = getPondAccountState(account.accountId);
+    const client = state?.client ?? new PondClient({
+      baseUrl: account.config.pond_url,
+      token: account.config.api_key,
+    });
+    const orgId = state?.orgId ?? account.config.org_id;
+    const chatId = to;
+
+    const req: SendMessageRequest = {
+      message_type: "text",
+      content: { text },
+    };
+    const msg = await client.sendMessage(orgId, chatId, req);
+    return { channel: "pond", messageId: msg.id, channelId: chatId };
+  },
+};

package/src/runtime.ts

@@ -0,0 +1,52 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PondClient } from "@pnds/sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setPondRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getPondRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Pond runtime not initialized");
+  }
+  return runtime;
+}
+
+// Cached client state per account, populated by gateway.ts startAccount
+export type PondAccountState = {
+  client: PondClient;
+  orgId: string;
+  agentUserId: string;
+};
+
+const accountStates = new Map<string, PondAccountState>();
+
+export function setPondAccountState(accountId: string, state: PondAccountState) {
+  accountStates.set(accountId, state);
+}
+
+export function removePondAccountState(accountId: string) {
+  accountStates.delete(accountId);
+}
+
+export function getPondAccountState(accountId: string): PondAccountState | undefined {
+  return accountStates.get(accountId);
+}
+
+export function getAllPondAccountStates(): ReadonlyMap<string, PondAccountState> {
+  return new Map(accountStates);
+}
+
+// Session key → original chat ID mapping.
+// OpenClaw normalizes session keys to lowercase, but Pond IDs are case-sensitive.
+const sessionChatIdMap = new Map<string, string>();
+
+export function setSessionChatId(sessionKey: string, chatId: string) {
+  sessionChatIdMap.set(sessionKey.toLowerCase(), chatId);
+}
+
+export function getSessionChatId(sessionKey: string): string | undefined {
+  return sessionChatIdMap.get(sessionKey.toLowerCase());
+}

package/src/session.ts

@@ -0,0 +1,31 @@
+const POND_SESSION_PREFIX = "agent:main:pond:";
+
+/** Build OpenClaw session key from Pond account, chat type, and chat ID. */
+export function buildSessionKey(accountId: string, chatType: string, chatId: string): string {
+  return `${POND_SESSION_PREFIX}${accountId}:${chatType}:${chatId}`;
+}
+
+/**
+ * Extract account ID from an OpenClaw session key.
+ * Format: "agent:main:pond:{accountId}:{type}:{chatId}"
+ */
+export function extractAccountIdFromSessionKey(sessionKey: string | undefined): string | undefined {
+  if (!sessionKey?.startsWith(POND_SESSION_PREFIX)) return undefined;
+  const rest = sessionKey.slice(POND_SESSION_PREFIX.length);
+  const firstColon = rest.indexOf(":");
+  if (firstColon < 0) return undefined;
+  return rest.slice(0, firstColon) || undefined;
+}
+
+/**
+ * Extract chat ID from an OpenClaw session key.
+ * Format: "agent:main:pond:{accountId}:{type}:{chatId}"
+ */
+export function extractChatIdFromSessionKey(sessionKey: string | undefined): string | undefined {
+  if (!sessionKey?.startsWith(POND_SESSION_PREFIX)) return undefined;
+  const rest = sessionKey.slice(POND_SESSION_PREFIX.length);
+  // Skip accountId and chatType segments
+  const parts = rest.split(":");
+  if (parts.length < 3) return undefined;
+  return parts.slice(2).join(":") || undefined;
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+export type PondChannelConfig = {
+  enabled?: boolean;
+  /** Pond server URL, e.g. "https://pond.example.com" */
+  pond_url: string;
+  /** Agent API key (agk_xxx) */
+  api_key: string;
+  /** Organization ID */
+  org_id: string;
+  /** WS Gateway URL (defaults to pond_url with ws:// scheme + /ws path) */
+  ws_url?: string;
+};
+
+export type ResolvedPondAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  config: PondChannelConfig;
+};