@pnds/pond 1.1.0 → 1.2.0

package/src/wiki-tools.ts

@@ -0,0 +1,370 @@
+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 {
+  getWikiBlob,
+  getWikiChangesetDiff,
+  getWikiOutline,
+  queryWiki,
+  getWikiSection,
+  getWikiTree,
+  getWikiWorkspaceDiff,
+  getWikiWorkspaceStatus,
+  listWikis,
+  proposeWikiChangeset,
+  searchWiki,
+  type PondContext,
+} from "@pnds/cli/wiki";
+import {
+  getActiveRunId,
+  getAllPondAccountStates,
+  getDispatchMessageId,
+  getPondAccountState,
+  getSessionChatId,
+  getSessionMessageId,
+} from "./runtime.js";
+import { extractAccountIdFromSessionKey } from "./session.js";
+
+const WikiTreeSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  path: Type.Optional(Type.String({ minLength: 1, description: "Tree path prefix." })),
+  ref: Type.Optional(Type.String({ minLength: 1, description: "Git ref to inspect." })),
+});
+
+const WikiBlobSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  path: Type.String({ minLength: 1, description: "File path inside the wiki." }),
+  ref: Type.Optional(Type.String({ minLength: 1, description: "Git ref to inspect." })),
+});
+
+const WikiStatusSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+});
+
+const WikiDiffSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+});
+
+const WikiSearchSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  query: Type.String({ minLength: 1, description: "Search query." }),
+  ref: Type.Optional(Type.String({ minLength: 1, description: "Git ref to inspect." })),
+  pathPrefix: Type.Optional(Type.String({ minLength: 1, description: "Restrict search to a path prefix." })),
+  limit: Type.Optional(Type.Number({ minimum: 1, description: "Maximum number of results." })),
+  includeContent: Type.Optional(Type.Boolean({ description: "Include full section content in each result." })),
+});
+
+const WikiQuerySchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  query: Type.String({ minLength: 1, description: "Natural-language query." }),
+  ref: Type.Optional(Type.String({ minLength: 1, description: "Git ref to inspect." })),
+  pathPrefix: Type.Optional(Type.String({ minLength: 1, description: "Restrict the query to a path prefix." })),
+  limit: Type.Optional(Type.Number({ minimum: 1, description: "Maximum number of section results." })),
+  includeContent: Type.Optional(Type.Boolean({ description: "Include full section content in each result." })),
+});
+
+const WikiOutlineSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  ref: Type.Optional(Type.String({ minLength: 1, description: "Git ref to inspect." })),
+  pathPrefix: Type.Optional(Type.String({ minLength: 1, description: "Restrict outline to a path prefix." })),
+});
+
+const WikiSectionSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  nodeId: Type.String({ minLength: 1, description: "Section node ID returned by wiki_search." }),
+  ref: Type.Optional(Type.String({ minLength: 1, description: "Git ref to inspect." })),
+});
+
+const WikiChangesetDiffSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  changesetId: Type.String({ minLength: 1, description: "Wiki changeset ID." }),
+});
+
+const WikiProposeSchema = Type.Object({
+  wiki: Type.String({ minLength: 1, description: "Wiki slug or ID." }),
+  title: Type.String({ minLength: 1, description: "Changeset title." }),
+  summary: Type.Optional(Type.String({ description: "Optional changeset summary." })),
+  changesetId: Type.Optional(Type.String({ minLength: 1, description: "Existing changeset ID to update." })),
+});
+
+type ToolSessionContext = {
+  sessionKey?: string;
+  agentAccountId?: string;
+  agentId?: string;
+};
+
+function resolvePondContext(ctx: ToolSessionContext): PondContext {
+  const accountId = ctx.agentAccountId ?? extractAccountIdFromSessionKey(ctx.sessionKey);
+  if (accountId) {
+    const state = getPondAccountState(accountId);
+    if (state) {
+      return {
+        client: state.client,
+        orgId: state.orgId,
+        agentId: ctx.agentId ?? process.env.POND_AGENT_ID,
+        mountRoot: state.wikiMountRoot,
+      };
+    }
+  }
+
+  const states = Array.from(getAllPondAccountStates().values());
+  if (states.length === 1) {
+    return {
+      client: states[0].client,
+      orgId: states[0].orgId,
+      agentId: ctx.agentId ?? process.env.POND_AGENT_ID,
+      mountRoot: states[0].wikiMountRoot,
+    };
+  }
+
+  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,
+      agentId: ctx.agentId ?? process.env.POND_AGENT_ID,
+    };
+  }
+
+  throw new Error(
+    "Pond wiki tools are unavailable: missing live Pond runtime state and POND_API_URL/POND_API_KEY/POND_ORG_ID.",
+  );
+}
+
+function formatWikiBlobResult(result: Awaited<ReturnType<typeof getWikiBlob>>) {
+  return {
+    wiki: {
+      id: result.wiki.id,
+      slug: result.wiki.slug,
+      name: result.wiki.name,
+    },
+    blob: {
+      path: result.blob.path,
+      ref: result.blob.ref,
+      size: result.blob.size,
+      mime_type: result.blob.mime_type,
+      is_binary: result.blob.is_binary,
+      encoding: result.blob.encoding,
+    },
+    text: result.text,
+  };
+}
+
+async function resolveWorkflowContext(ctx: ToolSessionContext) {
+  if (!ctx.sessionKey) {
+    return {};
+  }
+  const accountId = ctx.agentAccountId ?? extractAccountIdFromSessionKey(ctx.sessionKey);
+  const chatId = getSessionChatId(ctx.sessionKey);
+  const state = accountId ? getPondAccountState(accountId) : undefined;
+  const runId = state ? await getActiveRunId(state, ctx.sessionKey) : undefined;
+
+  // Issue 1: source_chat_id is a FK to the chats table — only set it for actual chat IDs.
+  // Task dispatches store a tsk_* ID here which would cause a DB FK violation.
+  const sourceChatId = chatId?.startsWith("cht_") ? chatId : undefined;
+
+  // Issue 2: prefer dispatch-time snapshot over the mutable session map to avoid
+  // reading a stale message ID when a new inbound message arrives mid-dispatch.
+  const sourceMessageId =
+    getDispatchMessageId(ctx.sessionKey) ?? getSessionMessageId(ctx.sessionKey);
+
+  return {
+    sourceChatId,
+    sourceMessageId,
+    sourceRunId: runId,
+  };
+}
+
+function createWikiTools(toolCtx: ToolSessionContext): AnyAgentTool[] {
+  const pondContext = () => resolvePondContext(toolCtx);
+  const workflowContext = () => resolveWorkflowContext(toolCtx);
+  return [
+    {
+      label: "Wiki List",
+      name: "wiki_list",
+      description: "List all Pond wikis in the current organization.",
+      parameters: Type.Object({}),
+      execute: async () => {
+        return jsonResult(await listWikis(pondContext()));
+      },
+    },
+    {
+      label: "Wiki Status",
+      name: "wiki_status",
+      description: "Inspect the local mounted wiki workspace before proposing changes.",
+      parameters: WikiStatusSchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await getWikiWorkspaceStatus(pondContext(), readStringParam(params, "wiki", { required: true })),
+        );
+      },
+    },
+    {
+      label: "Wiki Diff",
+      name: "wiki_diff",
+      description: "Read the current unified diff for the local mounted wiki workspace.",
+      parameters: WikiDiffSchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await getWikiWorkspaceDiff(pondContext(), readStringParam(params, "wiki", { required: true })),
+        );
+      },
+    },
+    {
+      label: "Wiki Tree",
+      name: "wiki_tree",
+      description: "List files and directories under a Pond wiki path.",
+      parameters: WikiTreeSchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await getWikiTree(pondContext(), readStringParam(params, "wiki", { required: true }), {
+            path: readStringParam(params, "path"),
+            ref: readStringParam(params, "ref"),
+          }),
+        );
+      },
+    },
+    {
+      label: "Wiki Blob",
+      name: "wiki_blob",
+      description: "Read a Pond wiki file. Use after wiki_search or wiki_tree narrows the target.",
+      parameters: WikiBlobSchema,
+      execute: async (_toolCallId, params) => {
+        const result = await getWikiBlob(pondContext(), readStringParam(params, "wiki", { required: true }), {
+          path: readStringParam(params, "path", { required: true }),
+          ref: readStringParam(params, "ref"),
+        });
+        return jsonResult(formatWikiBlobResult(result));
+      },
+    },
+    {
+      label: "Wiki Search",
+      name: "wiki_search",
+      description: "Search Pond wiki sections by heading and content. Prefer this before reading full files.",
+      parameters: WikiSearchSchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await searchWiki(
+            pondContext(),
+            readStringParam(params, "wiki", { required: true }),
+            readStringParam(params, "query", { required: true }),
+            {
+              ref: readStringParam(params, "ref"),
+              pathPrefix: readStringParam(params, "pathPrefix"),
+              limit: readNumberParam(params, "limit", { integer: true }),
+              includeContent: params.includeContent === true,
+            },
+          ),
+        );
+      },
+    },
+    {
+      label: "Wiki Query",
+      name: "wiki_query",
+      description: "Run a tree-aware Pond wiki query that first narrows documents and then selects the best sections.",
+      parameters: WikiQuerySchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await queryWiki(
+            pondContext(),
+            readStringParam(params, "wiki", { required: true }),
+            readStringParam(params, "query", { required: true }),
+            {
+              ref: readStringParam(params, "ref"),
+              pathPrefix: readStringParam(params, "pathPrefix"),
+              limit: readNumberParam(params, "limit", { integer: true }),
+              includeContent: params.includeContent === true,
+            },
+          ),
+        );
+      },
+    },
+    {
+      label: "Wiki Outline",
+      name: "wiki_outline",
+      description: "Read the structural outline of a Pond wiki or a specific path prefix before drilling into sections.",
+      parameters: WikiOutlineSchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await getWikiOutline(pondContext(), readStringParam(params, "wiki", { required: true }), {
+            ref: readStringParam(params, "ref"),
+            pathPrefix: readStringParam(params, "pathPrefix"),
+          }),
+        );
+      },
+    },
+    {
+      label: "Wiki Section",
+      name: "wiki_section",
+      description: "Read the full body of a Pond wiki section identified by nodeId from wiki_search.",
+      parameters: WikiSectionSchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await getWikiSection(pondContext(), readStringParam(params, "wiki", { required: true }), {
+            nodeId: readStringParam(params, "nodeId", { required: true }),
+            ref: readStringParam(params, "ref"),
+          }),
+        );
+      },
+    },
+    {
+      label: "Wiki Changeset Diff",
+      name: "wiki_changeset_diff",
+      description: "Fetch the unified diff and file summary for a Pond wiki changeset.",
+      parameters: WikiChangesetDiffSchema,
+      execute: async (_toolCallId, params) => {
+        return jsonResult(
+          await getWikiChangesetDiff(
+            pondContext(),
+            readStringParam(params, "wiki", { required: true }),
+            readStringParam(params, "changesetId", { required: true }),
+          ),
+        );
+      },
+    },
+    {
+      label: "Wiki Propose",
+      name: "wiki_propose",
+      description: "Create or update a proposed wiki changeset from the current local mounted workspace.",
+      parameters: WikiProposeSchema,
+      execute: async (_toolCallId, params) => {
+        const workflow = await workflowContext();
+        return jsonResult(
+          await proposeWikiChangeset(pondContext(), readStringParam(params, "wiki", { required: true }), {
+            title: readStringParam(params, "title", { required: true }),
+            summary: readStringParam(params, "summary"),
+            changesetId: readStringParam(params, "changesetId"),
+            sourceChatId: workflow.sourceChatId,
+            sourceMessageId: workflow.sourceMessageId,
+            sourceRunId: workflow.sourceRunId,
+          }),
+        );
+      },
+    },
+  ];
+}
+
+export function registerPondWikiTools(api: OpenClawPluginApi) {
+  api.registerTool(
+    (ctx) => createWikiTools(ctx),
+    {
+      names: [
+        "wiki_list",
+        "wiki_status",
+        "wiki_diff",
+        "wiki_tree",
+        "wiki_blob",
+        "wiki_search",
+        "wiki_query",
+        "wiki_outline",
+        "wiki_section",
+        "wiki_changeset_diff",
+        "wiki_propose",
+      ],
+    },
+  );
+}