@pnds/pond 1.1.0 → 1.2.1

package/src/hooks.ts

@@ -1,6 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { extractAccountIdFromSessionKey } from "./session.js";
-import { getActiveRunId, getPondAccountState, getSessionChatId } from "./runtime.js";
+import { clearDispatchMessageId, clearSessionMessageId, getActiveRunId, getPondAccountState, getSessionChatId } from "./runtime.js";
+import { loadToolsMarkdown } from "./tools-md.js";
 
 /**
  * Resolve the PondClient + orgId + runId for a hook context.
@@ -24,42 +25,73 @@ async function resolveClientForHook(sessionKey: string | undefined) {
   return { ...state, chatId, activeRunId };
 }
 
-const POND_CLI_CONTEXT = `## Pond CLI
+const ORCHESTRATOR_PREFIX = `## CRITICAL — Pond Orchestrator Mode
 
-You have access to the Pond platform via the \`@pnds/cli\` CLI. Auth is pre-configured — just run commands directly.
+> **Your text output is completely invisible.** No user or agent will ever see
+> anything you write as plain text. The ONLY way to communicate is through
+> Pond action tools. If you respond with text alone, your response is silently
+> discarded.
 
-\`\`\`
-npx @pnds/cli@latest whoami                          # Check your identity
-npx @pnds/cli@latest agents list                     # List all agents (name, model, status)
-npx @pnds/cli@latest dm <name-or-id> --text "..."    # DM a user by name or ID (auto-creates chat)
-npx @pnds/cli@latest dm <name-or-id> --text "..." --no-reply  # DM, signal no reply expected
-npx @pnds/cli@latest chats list                      # List chats
-npx @pnds/cli@latest messages list <chatId>          # Read chat history
-npx @pnds/cli@latest messages send <chatId> --text "..." # Send a message
-npx @pnds/cli@latest messages send <chatId> --text "..." --no-reply  # Send, no reply expected
-npx @pnds/cli@latest tasks list [--status ...]       # List tasks
-npx @pnds/cli@latest tasks create --title "..."      # Create a task
-npx @pnds/cli@latest tasks update <taskId> --status in_progress
-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
-\`\`\`
+You are the Pond orchestrator. Events from multiple chats and tasks arrive as
+structured \`[Event: ...]\` blocks. You decide how to handle each event and act
+through tools.
 
-Run \`npx @pnds/cli@latest --help\` or \`npx @pnds/cli@latest <command> --help\` for full options. Output is JSON.
+### How to Reply to a Message
 
-## Agent-to-Agent Interaction
+When you receive \`[Event: message.new]\` with \`[Chat: ... (cht_abc123)]\`:
+
+    pond_reply(chatId: "cht_abc123", text: "Your response here")
+
+If the event includes \`[Thread: 01JWC...]\`, reply inside the thread:
+
+    pond_reply(chatId: "cht_abc123", threadRootId: "01JWC...", text: "Thread reply here")
+
+DO NOT write text. ONLY \`pond_reply\` delivers messages to users.
+
+### How to Act on a Task
+
+When you receive \`[Event: task.assigned]\` with \`[Task: ... (tsk_xyz789)]\`:
+
+- \`pond_task_comment(taskId: "tsk_xyz789", body: "Starting work...")\` — post progress
+- \`pond_task_update(taskId: "tsk_xyz789", status: "in_progress")\` — change status
+
+### Pond Action Tools
+
+- \`pond_reply\` — Send a text message to a chat. Params: \`chatId\`, \`text\`, optional \`threadRootId\`, \`noReply\`.
+- \`pond_dm\` — Send a direct message to a user by ID (auto-creates DM chat). Params: \`userId\`, \`text\`, optional \`noReply\`. Use this for proactive outreach (e.g., notifying a task assigner of completion).
+- \`pond_task_comment\` — Post a comment on a task. Params: \`taskId\`, \`body\`.
+- \`pond_task_update\` — Update task fields (status, title, description, priority). Params: \`taskId\`, plus optional fields.
+- \`pond_chat_history\` — Read recent messages from a chat (default 20, max 50). Params: \`chatId\`, optional \`limit\`, \`before\`, \`threadRootId\`.
+- \`pond_typing\` — Start or stop the typing indicator. Params: \`chatId\`, \`action\` ("start" | "stop").
+
+### Sub-Agents
+
+For long-running tasks, use \`sessions_spawn\` to delegate to a sub-agent. Return quickly so the orchestrator can process other events.
+
+When a sub-agent completes and you receive a completion event, deliver the result to the relevant chat using \`pond_reply\` (or \`pond_dm\` if the target is a user, not a chat). Do NOT rely on text output — it is invisible.
+
+### Agent-to-Agent Interaction
 
 When you receive a message from another agent (not a human):
-- If the message has a no_reply hint, you may still reason and use tools, but your response will not be sent to chat.
-- If you have nothing meaningful to add to the conversation, produce an empty response to avoid unnecessary back-and-forth.
-- Use --no-reply when sending messages that don't require a response (e.g., delivering results, FYI notifications).`;
+- If the message has a \`no_reply\` hint, do not call \`pond_reply\`. You may still reason and use other tools.
+- If you have nothing meaningful to add, produce an empty response to avoid unnecessary back-and-forth.
+- Use \`pond_reply\` with \`noReply: true\` when sending messages that don't need a response (FYI, results delivery).
+
+### Prohibitions
+
+- **DO NOT** write text responses — they are invisible and silently discarded.
+- **DO NOT** use the Pond CLI (\`@pnds/cli\`) to send messages — use \`pond_reply\` for chat replies and \`pond_dm\` for direct messages.
+- **DO NOT** use the \`message\` tool to send to Pond chats — use \`pond_reply\`.`;
+
+// Load wiki tools, CLI docs, and other tool docs from TOOLS.md (maintained separately)
+const POND_ORCHESTRATOR_CONTEXT = ORCHESTRATOR_PREFIX + "\n\n" + loadToolsMarkdown();
 
 export function registerPondHooks(api: OpenClawPluginApi) {
   const log = api.logger;
 
   // Inject CLI awareness into agent system prompt
   api.on("before_prompt_build", () => {
-    return { prependContext: POND_CLI_CONTEXT };
+    return { prependSystemContext: POND_ORCHESTRATOR_CONTEXT };
   });
 
   // before_tool_call -> send tool_call step to AgentRun
@@ -125,6 +157,10 @@ export function registerPondHooks(api: OpenClawPluginApi) {
       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());
       }

package/src/index.ts

@@ -1,8 +1,10 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
 import { pondPlugin } from "./channel.js";
 import { setPondRuntime } from "./runtime.js";
 import { registerPondHooks } from "./hooks.js";
+import { registerPondWikiTools } from "./wiki-tools.js";
+import { registerPondActionTools } from "./action-tools.js";
 
 const plugin = {
   id: "pond",
@@ -12,6 +14,8 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     setPondRuntime(api.runtime);
     api.registerChannel({ plugin: pondPlugin });
+    registerPondWikiTools(api);
+    registerPondActionTools(api);
     registerPondHooks(api);
   },
 };

package/src/outbound.ts

@@ -1,4 +1,7 @@
-import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
+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 { PondClient } from "@pnds/sdk";

package/src/routing.ts

@@ -0,0 +1,48 @@
+import type { PondEvent, DispatchState } from "./runtime.js";
+
+/** Where an inbound event should be routed. */
+export type TriggerDisposition =
+  | { action: "main" }
+  | { action: "buffer-main" }
+  | { action: "buffer-fork"; forkKey: string }
+  | { action: "new-fork" };
+
+/** Pluggable strategy for routing triggers when main session is busy. */
+export type RoutingStrategy = (event: PondEvent, state: DispatchState) => TriggerDisposition;
+
+const MAX_CONCURRENT_FORKS = 20;
+
+/**
+ * Default routing strategy:
+ * - Same target as main → buffer-main (strict per-target serial ordering)
+ * - Active fork for same target → buffer into that fork
+ * - Too many forks → buffer-main (backpressure)
+ * - Otherwise → create a new fork
+ */
+export const defaultRoutingStrategy: RoutingStrategy = (event, state) => {
+  // P0: same target as main must stay serial — fork would see stale transcript
+  if (state.mainCurrentTargetId === event.targetId) {
+    return { action: "buffer-main" };
+  }
+
+  // Same target already has a fork → buffer into it
+  const existingForkKey = state.activeForks.get(event.targetId);
+  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
+
+  // Backpressure: cap concurrent forks to avoid unbounded fan-out
+  if (state.activeForks.size >= MAX_CONCURRENT_FORKS) {
+    return { action: "buffer-main" };
+  }
+
+  return { action: "new-fork" };
+};
+
+/** Route an inbound event based on current dispatch state. */
+export function routeTrigger(
+  event: PondEvent,
+  state: DispatchState,
+  strategy: RoutingStrategy = defaultRoutingStrategy,
+): TriggerDisposition {
+  if (!state.mainDispatching) return { action: "main" };
+  return strategy(event, state);
+}

package/src/runtime.ts

@@ -1,5 +1,5 @@
 import type { PluginRuntime } from "openclaw/plugin-sdk";
-import type { PondClient } from "@pnds/sdk";
+import type { PondClient, PondWs } from "@pnds/sdk";
 
 let runtime: PluginRuntime | null = null;
 
@@ -20,6 +20,9 @@ export type PondAccountState = {
   orgId: string;
   agentUserId: string;
   activeRuns: Map<string, Promise<string | undefined>>; // sessionKey (lowercased) → runId promise
+  wikiMountRoot?: string;
+  ws?: PondWs;
+  orchestratorSessionKey?: string;
 };
 
 /** Resolve run ID for a session, awaiting if the run is still being created. */
@@ -52,6 +55,10 @@ export function getAllPondAccountStates(): ReadonlyMap<string, PondAccountState>
 // Session key → original chat ID mapping.
 // OpenClaw normalizes session keys to lowercase, but Pond IDs are case-sensitive.
 const sessionChatIdMap = new Map<string, string>();
+const sessionMessageIdMap = new Map<string, string>();
+// Per-dispatch snapshot: message ID captured when a dispatch starts, immune to later overwrites.
+// Keyed by lowercased session key, cleared when the agent run ends.
+const dispatchMessageIdMap = new Map<string, string>();
 
 export function setSessionChatId(sessionKey: string, chatId: string) {
   sessionChatIdMap.set(sessionKey.toLowerCase(), chatId);
@@ -60,3 +67,79 @@ export function setSessionChatId(sessionKey: string, chatId: string) {
 export function getSessionChatId(sessionKey: string): string | undefined {
   return sessionChatIdMap.get(sessionKey.toLowerCase());
 }
+
+export function setSessionMessageId(sessionKey: string, messageId: string) {
+  sessionMessageIdMap.set(sessionKey.toLowerCase(), messageId);
+}
+
+export function getSessionMessageId(sessionKey: string): string | undefined {
+  return sessionMessageIdMap.get(sessionKey.toLowerCase());
+}
+
+export function clearSessionMessageId(sessionKey: string) {
+  sessionMessageIdMap.delete(sessionKey.toLowerCase());
+}
+
+/** Snapshot the message ID at dispatch time — immune to later session-level overwrites. */
+export function setDispatchMessageId(sessionKey: string, messageId: string) {
+  dispatchMessageIdMap.set(sessionKey.toLowerCase(), messageId);
+}
+
+/** Read the dispatch-time snapshot. Prefer this over getSessionMessageId for provenance. */
+export function getDispatchMessageId(sessionKey: string): string | undefined {
+  return dispatchMessageIdMap.get(sessionKey.toLowerCase());
+}
+
+export function clearDispatchMessageId(sessionKey: string) {
+  dispatchMessageIdMap.delete(sessionKey.toLowerCase());
+}
+
+// Per-dispatch noReply flag — deterministic suppression for agent-to-agent loop prevention.
+// When true, pond_reply hard-blocks sends and records a suppressed AgentStep instead.
+const dispatchNoReplyMap = new Map<string, boolean>();
+
+export function setDispatchNoReply(sessionKey: string, noReply: boolean) {
+  dispatchNoReplyMap.set(sessionKey.toLowerCase(), noReply);
+}
+
+export function getDispatchNoReply(sessionKey: string): boolean {
+  return dispatchNoReplyMap.get(sessionKey.toLowerCase()) ?? false;
+}
+
+export function clearDispatchNoReply(sessionKey: string) {
+  dispatchNoReplyMap.delete(sessionKey.toLowerCase());
+}
+
+/** Result from a completed fork dispatch, to be injected into main session's next turn. */
+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. */
+export type DispatchState = {
+  mainDispatching: boolean;
+  /** The targetId currently being processed by main. Used to enforce per-target serial ordering. */
+  mainCurrentTargetId?: string;
+  /** targetId → fork session key. One active fork per target at most. */
+  activeForks: Map<string, string>;
+  pendingForkResults: ForkResult[];
+  mainBuffer: PondEvent[];
+};
+
+/** Normalized inbound event from Pond. */
+export type PondEvent = {
+  type: "message" | "task";
+  targetId: string;       // chatId or taskId
+  targetName?: string;
+  targetType?: string;    // "direct" | "group" | "task"
+  senderId: string;
+  senderName: string;
+  messageId: string;
+  body: string;           // raw message text or task description
+  threadRootId?: string;
+  noReply?: boolean;
+  mediaFields?: Record<string, string | undefined>;
+};

package/src/session.ts

@@ -29,3 +29,8 @@ export function extractChatIdFromSessionKey(sessionKey: string | undefined): str
   if (parts.length < 3) return undefined;
   return parts.slice(2).join(":") || undefined;
 }
+
+/** Build the single orchestrator session key for all Pond events. */
+export function buildOrchestratorSessionKey(accountId: string): string {
+  return `${POND_SESSION_PREFIX}${accountId}:orchestrator`;
+}

package/src/tool-helpers.ts

@@ -0,0 +1,11 @@
+/**
+ * Wrap a value as an agent tool result with JSON text content.
+ * Replaces the SDK's jsonResult which was removed from public subpath exports
+ * in OpenClaw 2026.3.24.
+ */
+export function jsonResult(payload: unknown): { content: Array<{ type: "text"; text: string }>; details: unknown } {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}

package/src/tools-md.ts

@@ -0,0 +1,7 @@
+import fs from "node:fs";
+
+const TOOLS_MD_PATH = new URL("../TOOLS.md", import.meta.url);
+
+export function loadToolsMarkdown(): string {
+  return fs.readFileSync(TOOLS_MD_PATH, "utf8").trim();
+}

package/src/wiki-helper.ts

@@ -0,0 +1,157 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+type Logger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+type StartWikiHelperParams = {
+  accountId: string;
+  pondUrl: string;
+  apiKey: string;
+  orgId: string;
+  agentId: string;
+  stateDir: string;
+  log?: Logger;
+};
+
+type WikiHelperRuntime = {
+  mountRoot: string;
+  stop: () => void;
+};
+
+const DEFAULT_SYNC_TIMEOUT_MS = 30_000;
+const DEFAULT_WATCH_INTERVAL_SEC = 30;
+
+function isCommandMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function resolveMountRoot(stateDir: string): string {
+  return process.env.POND_WIKI_MOUNT_ROOT?.trim() || path.join(stateDir, "workspace");
+}
+
+function resolveWatchIntervalSec(): number {
+  const raw = process.env.POND_WIKI_REFRESH_INTERVAL_SEC?.trim();
+  if (!raw) {
+    return DEFAULT_WATCH_INTERVAL_SEC;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_WATCH_INTERVAL_SEC;
+}
+
+function buildWikiHelperEnv(params: StartWikiHelperParams, mountRoot: string): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    POND_API_URL: params.pondUrl,
+    POND_API_KEY: params.apiKey,
+    POND_ORG_ID: params.orgId,
+    POND_AGENT_ID: params.agentId,
+    POND_WIKI_MOUNT_ROOT: mountRoot,
+  };
+}
+
+async function runWikiSync(params: StartWikiHelperParams, env: NodeJS.ProcessEnv): Promise<"ok" | "missing" | "failed"> {
+  return new Promise((resolve) => {
+    let timedOut = false;
+    let settled = false;
+
+    const child = spawn("pond", ["wiki", "sync"], {
+      env,
+      stdio: "ignore",
+    });
+
+    const settle = (value: "ok" | "missing" | "failed") => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      params.log?.warn?.(`pond[${params.accountId}]: pond sync timed out after ${DEFAULT_SYNC_TIMEOUT_MS}ms`);
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 5_000).unref();
+    }, DEFAULT_SYNC_TIMEOUT_MS);
+    timer.unref();
+
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      if (isCommandMissing(error)) {
+        params.log?.warn?.(`pond[${params.accountId}]: pond not installed, skipping wiki auto-sync/watch`);
+        settle("missing");
+        return;
+      }
+      params.log?.warn?.(`pond[${params.accountId}]: pond sync failed to start: ${String(error)}`);
+      settle("failed");
+    });
+
+    child.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        settle("failed");
+        return;
+      }
+      if (code === 0) {
+        params.log?.info?.(`pond[${params.accountId}]: pond sync completed`);
+        settle("ok");
+        return;
+      }
+      params.log?.warn?.(
+        `pond[${params.accountId}]: pond sync exited with code=${code ?? "null"} signal=${signal ?? "null"}`,
+      );
+      settle("failed");
+    });
+  });
+}
+
+export async function startWikiHelper(params: StartWikiHelperParams): Promise<WikiHelperRuntime> {
+  const mountRoot = resolveMountRoot(params.stateDir);
+  const env = buildWikiHelperEnv(params, mountRoot);
+
+  const syncResult = await runWikiSync(params, env);
+  if (syncResult === "missing") {
+    return {
+      mountRoot,
+      stop() {},
+    };
+  }
+
+  const intervalSec = resolveWatchIntervalSec();
+  let stopped = false;
+  const watch = spawn("pond", ["wiki", "watch", "--interval-sec", String(intervalSec)], {
+    env,
+    stdio: "ignore",
+  });
+
+  watch.on("error", (error) => {
+    if (stopped) return;
+    if (isCommandMissing(error)) {
+      params.log?.warn?.(`pond[${params.accountId}]: pond disappeared before watch could start`);
+      return;
+    }
+    params.log?.warn?.(`pond[${params.accountId}]: pond watch failed: ${String(error)}`);
+  });
+
+  watch.on("exit", (code, signal) => {
+    if (stopped) return;
+    params.log?.warn?.(
+      `pond[${params.accountId}]: pond watch exited with code=${code ?? "null"} signal=${signal ?? "null"}`,
+    );
+  });
+
+  params.log?.info?.(`pond[${params.accountId}]: pond watch started (interval=${intervalSec}s)`);
+
+  return {
+    mountRoot,
+    stop() {
+      stopped = true;
+      if (watch.exitCode === null && watch.signalCode === null) {
+        watch.kill("SIGTERM");
+        setTimeout(() => watch.kill("SIGKILL"), 5_000).unref();
+      }
+    },
+  };
+}