@pnds/pond 1.2.0 → 1.2.1

package/TOOLS.md

@@ -23,32 +23,22 @@ Typical wiki edit flow:
 4. `wiki_status` and `wiki_diff` to verify the exact change
 5. `wiki_propose` to submit or update the wiki changeset
 
-## Pond CLI
+## Pond CLI (read-only)
 
-You also have access to the Pond platform via the `@pnds/cli` CLI. Auth is pre-configured.
+You have read-only access to the Pond platform via the `@pnds/cli` CLI. Auth is pre-configured.
+
+> **DO NOT use the CLI to send messages.** Use `pond_reply` for chat replies and `pond_dm` for direct messages.
+> **DO NOT use the CLI to create tasks.** Use task tools or sub-agents instead.
 
 ```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 members list                    # List org members
 ```
 
 Run `npx @pnds/cli@latest --help` or `npx @pnds/cli@latest <command> --help` for full options. Output is JSON.
-
-## 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnds/pond",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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.2.1",
+    "@pnds/cli": "1.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/action-tools.ts

@@ -50,6 +50,7 @@ function resolvePondState(ctx: ToolSessionContext) {
 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." }),
+  threadRootId: Type.Optional(Type.String({ description: "If provided, send the message as a thread reply under this root message ID." })),
   noReply: Type.Optional(Type.Boolean({ description: "If true, hints that no reply is expected." })),
 });
 
@@ -78,6 +79,12 @@ const TypingSchema = Type.Object({
   action: Type.Union([Type.Literal("start"), Type.Literal("stop")], { description: "Start or stop the typing indicator." }),
 });
 
+const DmSchema = Type.Object({
+  userId: Type.String({ minLength: 1, description: "Target user ID to DM." }),
+  text: Type.String({ minLength: 1, description: "Message text." }),
+  noReply: Type.Optional(Type.Boolean({ description: "If true, hints that no reply is expected." })),
+});
+
 // ---- Helpers ----
 
 function formatMessage(msg: Message): string {
@@ -110,6 +117,7 @@ function createActionTools(toolCtx: ToolSessionContext): AnyAgentTool[] {
         const s = state();
         const chatId = readStringParam(params, "chatId", { required: true });
         const text = readStringParam(params, "text", { required: true });
+        const threadRootId = readStringParam(params, "threadRootId");
         const noReply = params.noReply === true;
         const runId = s.activeRuns && toolCtx.sessionKey
           ? await getActiveRunId(s, toolCtx.sessionKey)
@@ -134,6 +142,7 @@ function createActionTools(toolCtx: ToolSessionContext): AnyAgentTool[] {
           message_type: "text",
           content: { text },
           agent_run_id: runId,
+          ...(threadRootId ? { thread_root_id: threadRootId } : {}),
           ...(noReply ? { hints: { no_reply: true } } : {}),
         });
         return jsonResult({ message_id: result.id, chat_id: chatId });
@@ -212,12 +221,36 @@ function createActionTools(toolCtx: ToolSessionContext): AnyAgentTool[] {
         return jsonResult({ ok: true });
       },
     },
+    {
+      label: "Pond DM",
+      name: "pond_dm",
+      description: "Send a direct message to a user by ID. Automatically finds or creates the DM chat.",
+      parameters: DmSchema,
+      execute: async (_toolCallId, params) => {
+        const s = state();
+        const userId = readStringParam(params, "userId", { 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;
+
+        const result = await s.client.sendDirectMessage(s.orgId, {
+          user_id: userId,
+          message_type: "text",
+          content: { text },
+          agent_run_id: runId,
+          ...(noReply ? { hints: { no_reply: true } } : {}),
+        });
+        return jsonResult({ chat_id: result.chat.id, message_id: result.message.id });
+      },
+    },
   ];
 }
 
 export function registerPondActionTools(api: OpenClawPluginApi) {
   api.registerTool(
     (ctx) => createActionTools(ctx),
-    { names: ["pond_reply", "pond_task_comment", "pond_task_update", "pond_chat_history", "pond_typing"] },
+    { names: ["pond_reply", "pond_task_comment", "pond_task_update", "pond_chat_history", "pond_typing", "pond_dm"] },
   );
 }

package/src/config-manager.ts

@@ -19,6 +19,13 @@ interface ConfigManagerOpts {
 
 const CACHE_FILENAME = "pond-platform-config.json";
 
+/** All tool names registered by this plugin — must stay in sync with registerPondActionTools + registerPondWikiTools. */
+const POND_TOOL_NAMES = [
+  "pond_reply", "pond_dm", "pond_task_comment", "pond_task_update", "pond_chat_history", "pond_typing",
+  "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 +98,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

@@ -25,32 +25,63 @@ async function resolveClientForHook(sessionKey: string | undefined) {
   return { ...state, chatId, activeRunId };
 }
 
-const ORCHESTRATOR_PREFIX = `## Orchestrator Model
+const ORCHESTRATOR_PREFIX = `## CRITICAL — 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.
+> **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.
 
-## Pond Action 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 act
+through tools.
 
-- \`pond_reply\` — Send a text message to a chat. Params: \`chatId\`, \`text\`, optional \`noReply\`.
+### How to Reply to a Message
+
+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). Use this to get context on unfamiliar chats. Params: \`chatId\`, optional \`limit\`, \`before\`, \`threadRootId\`.
+- \`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").
 
-## Task Handling
-
-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.
-
-## Sub-Agents
+### Sub-Agents
 
 For long-running tasks, use \`sessions_spawn\` to delegate to a sub-agent. Return quickly so the orchestrator can process other events.
 
-## Agent-to-Agent Interaction
+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.
-- Replies go through \`pond_reply\` — use \`noReply: true\` 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();
@@ -60,7 +91,7 @@ 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