@pnds/pond 1.2.0 → 1.3.0

package/TOOLS.md

@@ -25,30 +25,38 @@ Typical wiki edit flow:
 
 ## Pond CLI
 
-You also have access to the Pond platform via the `@pnds/cli` CLI. Auth is pre-configured.
+You have full access to the Pond platform via the `@pnds/cli` CLI. Auth and
+runtime context (org, agent run ID, current chat) are pre-configured via
+environment variables — no manual setup needed.
+
+### Sending Messages
+
+```bash
+npx @pnds/cli@latest messages send [chatId] --text "..."  # chatId defaults to POND_CHAT_ID
+npx @pnds/cli@latest messages send --text "..." --thread-root-id <id>
+npx @pnds/cli@latest messages send --text "..." --no-reply  # FYI, no response expected
+npx @pnds/cli@latest dm <nameOrId> --text "..."             # DM by user ID or display name
+```
+
+### Reading Data
 
 ```bash
 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 agents list                     # List all agents
 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 users get <userId>              # Get user by ID
 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.
+### Task Operations
 
-## Agent-to-Agent Interaction
+```bash
+npx @pnds/cli@latest tasks comments add <taskId> --body "..."
+npx @pnds/cli@latest tasks update <taskId> --status in_progress
+npx @pnds/cli@latest tasks create --title "..." [--assignee-id ...] [--project-id ...]
+```
 
-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).
+Run `npx @pnds/cli@latest --help` or `npx @pnds/cli@latest <command> --help` for full options. Output is JSON.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnds/pond",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "OpenClaw channel plugin for Pond IM",
   "license": "MIT",
   "repository": {
@@ -16,8 +16,8 @@
   ],
   "dependencies": {
     "@sinclair/typebox": "^0.34.48",
-    "@pnds/cli": "1.2.0",
-    "@pnds/sdk": "1.2.0"
+    "@pnds/sdk": "1.3.0",
+    "@pnds/cli": "1.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/config-manager.ts

@@ -19,6 +19,12 @@ interface ConfigManagerOpts {
 
 const CACHE_FILENAME = "pond-platform-config.json";
 
+/** All tool names registered by this plugin — must stay in sync with registerPondWikiTools. */
+const POND_TOOL_NAMES = [
+  "wiki_list", "wiki_status", "wiki_diff", "wiki_tree", "wiki_blob",
+  "wiki_search", "wiki_query", "wiki_outline", "wiki_section", "wiki_changeset_diff", "wiki_propose",
+];
+
 function cachePath(stateDir: string): string {
   return path.join(stateDir, CACHE_FILENAME);
 }
@@ -91,6 +97,17 @@ function applyToOpenClawConfig(
     existing.agents = agents;
   }
 
+  // Ensure Pond plugin tools are allowed alongside whatever tools.profile is set.
+  // Uses `alsoAllow` (additive) so user's profile choice is preserved.
+  const tools =
+    typeof existing.tools === "object"
+      && existing.tools !== null
+      && !Array.isArray(existing.tools)
+      ? (existing.tools as Record<string, unknown>)
+      : {};
+  tools.alsoAllow = POND_TOOL_NAMES;
+  existing.tools = tools;
+
   // Atomic write
   const tmpPath = `${configPath}.tmp`;
   fs.mkdirSync(path.dirname(configPath), { recursive: true });

package/src/hooks.ts

@@ -1,6 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { extractAccountIdFromSessionKey } from "./session.js";
-import { clearDispatchMessageId, clearSessionMessageId, getActiveRunId, getPondAccountState, getSessionChatId } from "./runtime.js";
+import { clearDispatchMessageId, clearSessionMessageId, getActiveRunId, getDispatchMessageId, getDispatchNoReply, getPondAccountState, getSessionChatId } from "./runtime.js";
 import { loadToolsMarkdown } from "./tools-md.js";
 
 /**
@@ -25,32 +25,77 @@ async function resolveClientForHook(sessionKey: string | undefined) {
   return { ...state, chatId, activeRunId };
 }
 
-const ORCHESTRATOR_PREFIX = `## Orchestrator Model
+const ORCHESTRATOR_PREFIX = `## Pond Orchestrator Mode
 
-You are an orchestrator agent. Events arrive as structured \`[Event: ...]\` blocks. Your text output is internal reasoning only — users cannot see it. All visible actions must go through tools.
+You are the Pond orchestrator. Events from multiple chats and tasks arrive as
+structured \`[Event: ...]\` blocks. You decide how to handle each event and
+respond using Bash commands via the Pond CLI.
 
-## Pond Action Tools
+Your text output is internal (not delivered to users). Use the CLI to interact.
 
-- \`pond_reply\` — Send a text message to a chat. Params: \`chatId\`, \`text\`, optional \`noReply\`.
-- \`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). Use this to get context on unfamiliar chats. Params: \`chatId\`, optional \`limit\`, \`before\`, \`threadRootId\`.
-- \`pond_typing\` — Start or stop the typing indicator. Params: \`chatId\`, \`action\` ("start" | "stop").
+### Pond CLI — Pre-Authenticated
 
-## Task Handling
+The Pond CLI (\`npx @pnds/cli@latest\`) is pre-authenticated via environment
+variables injected into every Bash command. You do NOT need to set
+POND_API_URL, POND_API_KEY, etc. — they are already configured.
 
-Use \`pond_task_comment\` to communicate progress on tasks. Use \`pond_task_update\` to change task status (e.g., in_progress, done), title, description, or priority.
+\`POND_CHAT_ID\` is set to the chat that triggered the current event. When
+replying to the trigger chat, you can omit the chatId argument.
 
-## Sub-Agents
+### How to Reply to a Message
 
-For long-running tasks, use \`sessions_spawn\` to delegate to a sub-agent. Return quickly so the orchestrator can process other events.
+When you receive \`[Event: message.new]\` with \`[Chat: ... (cht_abc123)]\`:
 
-## Agent-to-Agent Interaction
+    npx @pnds/cli@latest messages send cht_abc123 --text "Your response here"
 
-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.
-- Replies go through \`pond_reply\` — use \`noReply: true\` when sending messages that don't require a response (e.g., delivering results, FYI notifications).`;
+Or, since POND_CHAT_ID is set to the trigger chat:
+
+    npx @pnds/cli@latest messages send --text "Your response here"
+
+For thread replies (when the event includes \`[Thread: 01JWC...]\`):
+
+    npx @pnds/cli@latest messages send --text "Thread reply" --thread-root-id 01JWC...
+
+### How to Send a Direct Message
+
+    npx @pnds/cli@latest dm usr_xyz --text "Hello"
+
+Or by display name:
+
+    npx @pnds/cli@latest dm "Alice" --text "Hello"
+
+### How to Act on a Task
+
+When you receive \`[Event: task.assigned]\` with \`[Task: ... (tsk_xyz789)]\`:
+
+    npx @pnds/cli@latest tasks comments add tsk_xyz789 --body "Starting work..."
+    npx @pnds/cli@latest tasks update tsk_xyz789 --status in_progress
+
+### Reading Data
+
+    npx @pnds/cli@latest messages list <chatId>
+    npx @pnds/cli@latest tasks list --status open
+    npx @pnds/cli@latest chats list
+    npx @pnds/cli@latest members list
+
+### 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, deliver the result using the CLI:
+
+    npx @pnds/cli@latest messages send <chatId> --text "Result: ..."
+
+### Agent-to-Agent Interaction
+
+When a message has a \`[Hint: no_reply]\`, do not send a reply. The CLI
+automatically suppresses sends when POND_NO_REPLY is set, but you should
+also skip unnecessary computation.
+
+Use \`--no-reply\` for FYI messages that don't need a response:
+
+    npx @pnds/cli@latest messages send <chatId> --text "FYI: done" --no-reply`;
 
 // Load wiki tools, CLI docs, and other tool docs from TOOLS.md (maintained separately)
 const POND_ORCHESTRATOR_CONTEXT = ORCHESTRATOR_PREFIX + "\n\n" + loadToolsMarkdown();
@@ -60,15 +105,16 @@ export function registerPondHooks(api: OpenClawPluginApi) {
 
   // Inject CLI awareness into agent system prompt
   api.on("before_prompt_build", () => {
-    return { prependContext: POND_ORCHESTRATOR_CONTEXT };
+    return { prependSystemContext: POND_ORCHESTRATOR_CONTEXT };
   });
 
-  // before_tool_call -> send tool_call step to AgentRun
-  // Fire-and-forget: before_tool_call is an awaited hook in OpenClaw (can block/modify
-  // tool params), so we must not block tool execution waiting for run creation.
-  api.on("before_tool_call", (event, ctx) => {
+  // before_tool_call -> (1) fire-and-forget step creation, (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(ctx.sessionKey);
+      const resolved = await resolveClientForHook(sessionKey);
       if (!resolved || !resolved.activeRunId || !event.toolCallId) return;
       try {
         await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.activeRunId, {
@@ -85,6 +131,40 @@ export function registerPondHooks(api: OpenClawPluginApi) {
         log?.warn(`pond hook before_tool_call failed: ${String(err)}`);
       }
     })();
+
+    // (2) ENV injection — only for the exec (Bash) tool
+    if (event.toolName !== "exec") return;
+    if (!sessionKey) return;
+    const accountId = extractAccountIdFromSessionKey(sessionKey);
+    if (!accountId) return;
+    const state = getPondAccountState(accountId);
+    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 (chatId) injectedEnv.POND_CHAT_ID = chatId;
+    if (triggerMsgId) injectedEnv.POND_TRIGGER_MESSAGE_ID = triggerMsgId;
+    if (noReply) injectedEnv.POND_NO_REPLY = "1";
+    if (state.wikiMountRoot) injectedEnv.POND_WIKI_MOUNT_ROOT = state.wikiMountRoot;
+
+    // OpenClaw context (upstream doesn't inject these into exec env yet)
+    injectedEnv.OPENCLAW_SESSION_KEY = sessionKey;
+    if (event.toolCallId) injectedEnv.OPENCLAW_TOOL_CALL_ID = event.toolCallId;
+
+    // Shallow merge — preserve agent's original env params
+    const existingEnv = (event.params as Record<string, unknown>)?.env as Record<string, string> | undefined;
+
+    return {
+      params: {
+        env: { ...existingEnv, ...injectedEnv },
+      },
+    };
   });
 
   // after_tool_call -> send tool_result step to AgentRun

package/src/index.ts

@@ -4,7 +4,6 @@ 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",
@@ -15,7 +14,6 @@ const plugin = {
     setPondRuntime(api.runtime);
     api.registerChannel({ plugin: pondPlugin });
     registerPondWikiTools(api);
-    registerPondActionTools(api);
     registerPondHooks(api);
   },
 };

package/src/runtime.ts

@@ -95,7 +95,7 @@ export function clearDispatchMessageId(sessionKey: string) {
 }
 
 // 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.
+// Injected as POND_NO_REPLY=1 into Bash env; the CLI checks and suppresses sends.
 const dispatchNoReplyMap = new Map<string, boolean>();
 
 export function setDispatchNoReply(sessionKey: string, noReply: boolean) {

package/src/action-tools.ts

@@ -1,223 +0,0 @@
-import { Type } from "@sinclair/typebox";
-import type { OpenClawPluginApi, AnyAgentTool } from "openclaw/plugin-sdk";
-import { readNumberParam, readStringParam } from "openclaw/plugin-sdk/param-readers";
-import { jsonResult } from "./tool-helpers.js";
-import { PondClient } from "@pnds/sdk";
-import type { Message } from "@pnds/sdk";
-import {
-  getActiveRunId,
-  getAllPondAccountStates,
-  getPondAccountState,
-  getDispatchNoReply,
-} from "./runtime.js";
-import { extractAccountIdFromSessionKey } from "./session.js";
-
-type ToolSessionContext = {
-  sessionKey?: string;
-  agentAccountId?: string;
-  agentId?: string;
-};
-
-function resolvePondState(ctx: ToolSessionContext) {
-  const accountId = ctx.agentAccountId ?? extractAccountIdFromSessionKey(ctx.sessionKey);
-  if (accountId) {
-    const state = getPondAccountState(accountId);
-    if (state) return state;
-  }
-
-  const states = Array.from(getAllPondAccountStates().values());
-  if (states.length === 1) return states[0];
-
-  const baseUrl = process.env.POND_API_URL?.trim();
-  const token = process.env.POND_API_KEY?.trim();
-  const orgId = process.env.POND_ORG_ID?.trim();
-  if (baseUrl && token && orgId) {
-    return {
-      client: new PondClient({ baseUrl, token }),
-      orgId,
-      agentUserId: "",
-      activeRuns: new Map<string, Promise<string | undefined>>(),
-    };
-  }
-
-  throw new Error(
-    "Pond action tools are unavailable: missing live Pond runtime state and POND_API_URL/POND_API_KEY/POND_ORG_ID.",
-  );
-}
-
-// ---- Schemas ----
-
-const ReplySchema = Type.Object({
-  chatId: Type.String({ minLength: 1, description: "Chat ID to send the message to." }),
-  text: Type.String({ minLength: 1, description: "Message text." }),
-  noReply: Type.Optional(Type.Boolean({ description: "If true, hints that no reply is expected." })),
-});
-
-const TaskCommentSchema = Type.Object({
-  taskId: Type.String({ minLength: 1, description: "Task ID to comment on." }),
-  body: Type.String({ minLength: 1, description: "Comment body text." }),
-});
-
-const TaskUpdateSchema = Type.Object({
-  taskId: Type.String({ minLength: 1, description: "Task ID to update." }),
-  status: Type.Optional(Type.String({ description: "New task status." })),
-  title: Type.Optional(Type.String({ description: "New task title." })),
-  description: Type.Optional(Type.String({ description: "New task description." })),
-  priority: Type.Optional(Type.String({ description: "New task priority." })),
-});
-
-const ChatHistorySchema = Type.Object({
-  chatId: Type.String({ minLength: 1, description: "Chat ID to read messages from." }),
-  limit: Type.Optional(Type.Number({ minimum: 1, maximum: 50, description: "Number of messages to fetch (default 20, max 50)." })),
-  before: Type.Optional(Type.String({ description: "Message ID cursor — fetch messages before this ID." })),
-  threadRootId: Type.Optional(Type.String({ description: "If provided, fetch messages within this thread instead of top-level messages." })),
-});
-
-const TypingSchema = Type.Object({
-  chatId: Type.String({ minLength: 1, description: "Chat ID for the typing indicator." }),
-  action: Type.Union([Type.Literal("start"), Type.Literal("stop")], { description: "Start or stop the typing indicator." }),
-});
-
-// ---- Helpers ----
-
-function formatMessage(msg: Message): string {
-  const senderName = msg.sender?.display_name ?? msg.sender_id;
-  const content = msg.content as Record<string, unknown>;
-  if (msg.message_type === "text") {
-    return `${senderName} (${msg.sender_id}): ${(content as { text?: string }).text ?? ""}`;
-  }
-  if (msg.message_type === "file") {
-    return `${senderName} (${msg.sender_id}): [file: ${(content as { file_name?: string }).file_name ?? "unknown"}]`;
-  }
-  if (msg.message_type === "system") {
-    return `[system: ${(content as { text?: string }).text ?? JSON.stringify(content)}]`;
-  }
-  return `${senderName} (${msg.sender_id}): [${msg.message_type}]`;
-}
-
-// ---- Tool factory ----
-
-function createActionTools(toolCtx: ToolSessionContext): AnyAgentTool[] {
-  const state = () => resolvePondState(toolCtx);
-
-  return [
-    {
-      label: "Pond Reply",
-      name: "pond_reply",
-      description: "Send a text message to a Pond chat.",
-      parameters: ReplySchema,
-      execute: async (_toolCallId, params) => {
-        const s = state();
-        const chatId = readStringParam(params, "chatId", { required: true });
-        const text = readStringParam(params, "text", { required: true });
-        const noReply = params.noReply === true;
-        const runId = s.activeRuns && toolCtx.sessionKey
-          ? await getActiveRunId(s, toolCtx.sessionKey)
-          : undefined;
-
-        // Deterministic no_reply suppression: if the inbound event had no_reply hint,
-        // hard-block the send and record a suppressed step instead of posting to chat.
-        // This prevents agent-to-agent reply loops at the plugin layer (not just prompt).
-        if (toolCtx.sessionKey && getDispatchNoReply(toolCtx.sessionKey)) {
-          if (runId) {
-            try {
-              await s.client.createAgentStep(s.orgId, s.agentUserId, runId, {
-                step_type: "text",
-                content: { text, suppressed: true, reason: "no_reply" },
-              });
-            } catch { /* best-effort step recording */ }
-          }
-          return jsonResult({ suppressed: true, reason: "no_reply", chat_id: chatId });
-        }
-
-        const result = await s.client.sendMessage(s.orgId, chatId, {
-          message_type: "text",
-          content: { text },
-          agent_run_id: runId,
-          ...(noReply ? { hints: { no_reply: true } } : {}),
-        });
-        return jsonResult({ message_id: result.id, chat_id: chatId });
-      },
-    },
-    {
-      label: "Pond Task Comment",
-      name: "pond_task_comment",
-      description: "Post a comment on a Pond task.",
-      parameters: TaskCommentSchema,
-      execute: async (_toolCallId, params) => {
-        const s = state();
-        const taskId = readStringParam(params, "taskId", { required: true });
-        const body = readStringParam(params, "body", { required: true });
-        const result = await s.client.createTaskComment(s.orgId, taskId, { body });
-        return jsonResult(result);
-      },
-    },
-    {
-      label: "Pond Task Update",
-      name: "pond_task_update",
-      description: "Update fields on a Pond task (status, title, description, priority).",
-      parameters: TaskUpdateSchema,
-      execute: async (_toolCallId, params) => {
-        const s = state();
-        const taskId = readStringParam(params, "taskId", { required: true });
-        const update: Record<string, string> = {};
-        for (const field of ["status", "title", "description", "priority"] as const) {
-          const val = readStringParam(params, field);
-          if (val !== undefined) update[field] = val;
-        }
-        const result = await s.client.updateTask(s.orgId, taskId, update);
-        return jsonResult(result);
-      },
-    },
-    {
-      label: "Pond Chat History",
-      name: "pond_chat_history",
-      description: "Read recent messages from a Pond chat. Use this to get context on unfamiliar conversations.",
-      parameters: ChatHistorySchema,
-      execute: async (_toolCallId, params) => {
-        const s = state();
-        const chatId = readStringParam(params, "chatId", { required: true });
-        const limit = Math.min(readNumberParam(params, "limit", { integer: true }) ?? 20, 50);
-        const before = readStringParam(params, "before");
-        const threadRootId = readStringParam(params, "threadRootId");
-        const threadParams = threadRootId
-          ? { thread_root_id: threadRootId }
-          : { top_level: true as const };
-        const result = await s.client.getMessages(s.orgId, chatId, {
-          limit,
-          before,
-          ...threadParams,
-        });
-        const messages = result.data.map(formatMessage);
-        return jsonResult({
-          messages,
-          has_more: result.has_more,
-          ...(result.next_cursor ? { next_cursor: result.next_cursor } : {}),
-        });
-      },
-    },
-    {
-      label: "Pond Typing",
-      name: "pond_typing",
-      description: "Start or stop the typing indicator in a Pond chat.",
-      parameters: TypingSchema,
-      execute: async (_toolCallId, params) => {
-        const s = state();
-        if (!s.ws) {
-          return jsonResult({ error: "WebSocket not available — typing indicator requires a live connection." });
-        }
-        const chatId = readStringParam(params, "chatId", { required: true });
-        const action = readStringParam(params, "action", { required: true }) as "start" | "stop";
-        s.ws.sendTyping(chatId, action);
-        return jsonResult({ ok: true });
-      },
-    },
-  ];
-}
-
-export function registerPondActionTools(api: OpenClawPluginApi) {
-  api.registerTool(
-    (ctx) => createActionTools(ctx),
-    { names: ["pond_reply", "pond_task_comment", "pond_task_update", "pond_chat_history", "pond_typing"] },
-  );
-}