@pnds/pond 1.0.1 → 1.2.0

package/TOOLS.md

@@ -0,0 +1,54 @@
+# Pond Tools
+
+## Pond Wiki Tools
+
+Use native Pond wiki tools for wiki lookup and editing instead of shelling out to the CLI.
+
+- `wiki_list` to find candidate wikis
+- `wiki_query` as the primary tree-aware retrieval tool
+- `wiki_outline` to inspect the local structural outline of a wiki or path prefix
+- `wiki_search` as a simpler lexical fallback
+- `wiki_section` to expand a result by `nodeId`
+- `wiki_blob` only when you need the whole file
+- `wiki_status` to inspect local mounted wiki edits
+- `wiki_diff` to review the local mounted wiki patch
+- `wiki_propose` to open or update a wiki changeset after editing
+- `wiki_changeset_diff` to inspect a wiki draft or changeset
+
+Typical wiki edit flow:
+
+1. `wiki_query` or `wiki_outline` to locate the right content
+2. `wiki_section` to read the exact section body you need
+3. Edit the mounted wiki files locally
+4. `wiki_status` and `wiki_diff` to verify the exact change
+5. `wiki_propose` to submit or update the wiki changeset
+
+## Pond CLI
+
+You also have access to the Pond platform via the `@pnds/cli` CLI. Auth is pre-configured.
+
+```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 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.0.1",
+  "version": "1.2.0",
   "description": "OpenClaw channel plugin for Pond IM",
   "license": "MIT",
   "repository": {
@@ -11,20 +11,33 @@
   "type": "module",
   "files": [
     "src",
+    "TOOLS.md",
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@pnds/sdk": "1.0.1"
+    "@sinclair/typebox": "^0.34.48",
+    "@pnds/cli": "1.2.0",
+    "@pnds/sdk": "1.2.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "2026.3.24",
     "typescript": "^5.7.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2025"
+    "@mariozechner/pi-coding-agent": "*",
+    "openclaw": ">=2026.3.24"
   },
   "openclaw": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "install": {
+      "minHostVersion": ">=2026.3.24"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --test test/*.test.mjs"
   }
 }

package/src/action-tools.ts

@@ -0,0 +1,223 @@
+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"] },
+  );
+}

package/src/channel.ts

@@ -1,10 +1,10 @@
-import type { ChannelPlugin, ChannelMeta } from "openclaw/plugin-sdk";
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 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 = {
+const meta: ChannelPlugin["meta"] = {
   id: "pond",
   label: "Pond",
   selectionLabel: "Pond IM",

package/src/fork.ts

@@ -0,0 +1,213 @@
+// fork.ts — Fork-on-busy engine for orchestrator mode
+//
+// When the orchestrator's main session is busy, new events are handled by
+// forking the main session's transcript and dispatching to the fork in parallel.
+// The on-disk JSONL transcript always reflects the state BEFORE the current
+// dispatch (in-flight messages are memory-only), so the fork inherits all
+// prior history without race conditions.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { CURRENT_SESSION_VERSION, SessionManager } from "@mariozechner/pi-coding-agent";
+
+export type ForkSessionResult = {
+  sessionKey: string;
+  sessionId: string;
+  sessionFile: string;
+};
+
+// ---------------------------------------------------------------------------
+// Session store helpers — read sessions.json directly (SSOT for file paths)
+// ---------------------------------------------------------------------------
+
+type SessionStoreEntry = {
+  sessionId?: string;
+  sessionFile?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * Read sessions.json and find the entry for a given session key.
+ * OpenClaw may store keys in lowercase; we try both.
+ */
+function readStoreEntry(sessionsDir: string, sessionKey: string): SessionStoreEntry | null {
+  const storeFile = path.join(sessionsDir, "sessions.json");
+  try {
+    const store = JSON.parse(fs.readFileSync(storeFile, "utf-8")) as Record<string, SessionStoreEntry>;
+    return store[sessionKey] ?? store[sessionKey.toLowerCase()] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write or update an entry in sessions.json.
+ */
+function writeStoreEntry(sessionsDir: string, sessionKey: string, entry: SessionStoreEntry): boolean {
+  const storeFile = path.join(sessionsDir, "sessions.json");
+  try {
+    let store: Record<string, SessionStoreEntry> = {};
+    try {
+      store = JSON.parse(fs.readFileSync(storeFile, "utf-8"));
+    } catch { /* empty or missing — start fresh */ }
+    store[sessionKey.toLowerCase()] = entry;
+    fs.writeFileSync(storeFile, JSON.stringify(store, null, 2), { encoding: "utf-8" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delete an entry from sessions.json.
+ */
+function deleteStoreEntry(sessionsDir: string, sessionKey: string): void {
+  const storeFile = path.join(sessionsDir, "sessions.json");
+  try {
+    const store = JSON.parse(fs.readFileSync(storeFile, "utf-8")) as Record<string, unknown>;
+    delete store[sessionKey];
+    delete store[sessionKey.toLowerCase()];
+    fs.writeFileSync(storeFile, JSON.stringify(store, null, 2), { encoding: "utf-8" });
+  } catch {
+    // Best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Transcript file resolution (via session store)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the transcript file for a session key by reading the session store.
+ * Returns the absolute path, or null if not found.
+ */
+export function resolveTranscriptFile(sessionsDir: string, sessionKey: string): string | null {
+  const entry = readStoreEntry(sessionsDir, sessionKey);
+  if (!entry?.sessionId) return null;
+
+  // Prefer explicit sessionFile field
+  if (entry.sessionFile) {
+    const resolved = path.isAbsolute(entry.sessionFile)
+      ? entry.sessionFile
+      : path.join(sessionsDir, entry.sessionFile);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+
+  // Fallback: conventional {sessionId}.jsonl
+  const conventional = path.join(sessionsDir, `${entry.sessionId}.jsonl`);
+  if (fs.existsSync(conventional)) return conventional;
+
+  // Last resort: scan for files containing the sessionId
+  try {
+    const files = fs.readdirSync(sessionsDir);
+    const match = files.find((f) => f.includes(entry.sessionId!) && f.endsWith(".jsonl"));
+    return match ? path.join(sessionsDir, match) : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fork creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Fork the orchestrator session's transcript into a new parallel session.
+ *
+ * The fork inherits all history up to the current dispatch start (on-disk state).
+ * It gets its own session key, write lock, and can dispatch independently.
+ *
+ * Creates a session store entry with lineage metadata (spawnedBy).
+ */
+export function forkOrchestratorSession(opts: {
+  orchestratorSessionKey: string;
+  accountId: string;
+  transcriptFile: string;
+  sessionsDir: string;
+}): ForkSessionResult | null {
+  const { orchestratorSessionKey, accountId, transcriptFile, sessionsDir } = opts;
+
+  if (!fs.existsSync(transcriptFile)) return null;
+
+  try {
+    const manager = SessionManager.open(transcriptFile);
+    const leafId = manager.getLeafId();
+
+    let sessionId: string;
+    let sessionFile: string;
+
+    if (leafId) {
+      // Branch from the current leaf — inherits full transcript history
+      const branched = manager.createBranchedSession(leafId) ?? manager.getSessionFile();
+      const branchedId = manager.getSessionId();
+      if (branched && branchedId) {
+        sessionFile = branched;
+        sessionId = branchedId;
+      } else {
+        return null;
+      }
+    } else {
+      // Fallback: no leaf node — create a header-only fork file manually.
+      sessionId = crypto.randomUUID();
+      const timestamp = new Date().toISOString();
+      const fileTimestamp = timestamp.replace(/[:.]/g, "-");
+      sessionFile = path.join(
+        manager.getSessionDir(),
+        `${fileTimestamp}_${sessionId}.jsonl`,
+      );
+      const header = {
+        type: "session",
+        version: CURRENT_SESSION_VERSION,
+        id: sessionId,
+        timestamp,
+        cwd: manager.getCwd(),
+        parentSession: transcriptFile,
+      };
+      fs.writeFileSync(sessionFile, `${JSON.stringify(header)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+        flag: "wx",
+      });
+    }
+
+    const forkSessionKey = `${orchestratorSessionKey}:fork:${sessionId}`;
+
+    // Register in session store — fail closed if store is unwritable
+    const wrote = writeStoreEntry(sessionsDir, forkSessionKey, {
+      sessionId,
+      sessionFile: path.relative(sessionsDir, sessionFile),
+      updatedAt: Date.now(),
+      spawnedBy: orchestratorSessionKey,
+      parentSessionKey: orchestratorSessionKey,
+      forkedFromParent: true,
+    });
+    if (!wrote) return null;
+
+    return { sessionKey: forkSessionKey, sessionId, sessionFile };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fork cleanup (store-driven)
+// ---------------------------------------------------------------------------
+
+/**
+ * Clean up a fork session: delete transcript file AND session store entry.
+ */
+export function cleanupForkSession(opts: {
+  sessionFile: string;
+  sessionKey: string;
+  sessionsDir: string;
+}): void {
+  try {
+    if (fs.existsSync(opts.sessionFile)) {
+      fs.unlinkSync(opts.sessionFile);
+    }
+  } catch {
+    // Best-effort file cleanup
+  }
+  deleteStoreEntry(opts.sessionsDir, opts.sessionKey);
+}