pi-para 0.6.7 → 0.7.0

package/src/tools/query.ts

@@ -0,0 +1,63 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { QMDStore } from "qmd-engine";
+import type { ProjectScope } from "../scope.js";
+import type { ParaCategory } from "../wiki.js";
+import { queryWiki as queryWikiLib, formatQueryResults } from "../query.js";
+import { QUERY_PROMPT } from "../templates/prompts.js";
+import type { WikiQueryDetails } from "./schemas.js";
+
+// -- Factory: wiki_query execute ---------------------------------------------
+
+export function createQueryExecute(
+  _wikiDir: string,
+  store: QMDStore,
+  getScope: () => ProjectScope,
+  getGraphBoost?: () => boolean,
+) {
+  return async (
+    params: { query: string; global?: boolean; category?: ParaCategory; limit?: number },
+  ): Promise<AgentToolResult<WikiQueryDetails>> => {
+    const scope = getScope();
+    const result = await queryWikiLib(store, {
+      query: params.query,
+      global: params.global,
+      category: params.category,
+      limit: params.limit,
+      graphBoost: getGraphBoost?.() ?? true,
+    }, scope);
+
+    if (result.results.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No wiki pages found for "${params.query}". The wiki may not have content on this topic yet.`,
+          },
+        ],
+        details: {
+          resultCount: 0,
+          scopeUsed: result.wasGlobal ? "global" : scope.name,
+        },
+      };
+    }
+
+    const formatted = formatQueryResults(result.results);
+    const toolResultText = [
+      QUERY_PROMPT,
+      "",
+      `Query: "${params.query}"`,
+      `Scope: ${result.wasGlobal ? "global (all scopes)" : scope.name}`,
+      `Results: ${result.results.length}`,
+      "",
+      formatted,
+    ].join("\n");
+
+    return {
+      content: [{ type: "text", text: toolResultText }],
+      details: {
+        resultCount: result.results.length,
+        scopeUsed: result.wasGlobal ? "global" : scope.name,
+      },
+    };
+  };
+}

package/src/tools/schemas.ts

@@ -0,0 +1,157 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { LintReport } from "../lint.js";
+
+// -- Parameter schemas -------------------------------------------------------
+
+export const PARA_ENUM = StringEnum(
+  ["projects", "areas", "resources", "archives"] as const,
+  { description: "PARA category" },
+);
+
+export const PARA_ENUM_NO_ARCHIVES = StringEnum(
+  ["projects", "areas", "resources"] as const,
+  { description: "PARA category (archives excluded for new content)" },
+);
+
+export const WikiIngestParams = Type.Object({
+  source: Type.String({ description: "URL, file path, or raw text to ingest" }),
+  sourceType: Type.Optional(
+    StringEnum(["url", "file", "text"] as const, {
+      description: "Source type (auto-detected if omitted)",
+    }),
+  ),
+  category: Type.Optional(PARA_ENUM_NO_ARCHIVES),
+  scope: Type.Optional(
+    Type.Array(Type.String(), { description: "Scope tags for the ingested content" }),
+  ),
+});
+
+export const WikiQueryParams = Type.Object({
+  query: Type.String({ description: "Natural language search query" }),
+  global: Type.Optional(
+    Type.Boolean({ description: "Search all scopes, not just current project" }),
+  ),
+  category: Type.Optional(PARA_ENUM),
+  limit: Type.Optional(
+    Type.Number({ description: "Max results (default 10)" }),
+  ),
+});
+
+export const WikiEditSchema = Type.Object({
+  oldText: Type.String({ description: "Exact text to find in the page body" }),
+  newText: Type.String({ description: "Replacement text" }),
+});
+
+export const WikiWritePageSchema = Type.Object({
+  category: PARA_ENUM,
+  slug: Type.String({ description: "Page slug (lowercase, hyphens)" }),
+  title: Type.String({ description: "Page title" }),
+  scope: Type.Array(Type.String(), { description: "Scope tags" }),
+  tags: Type.Array(Type.String(), { description: "Topic tags" }),
+  body: Type.String({ description: "Page body in markdown (wiki summary format)" }),
+  mode: StringEnum(["create", "replace", "append", "edit"] as const, {
+    description: "Write mode: create new, replace existing, append to existing, or edit specific sections",
+  }),
+  edits: Type.Optional(Type.Array(WikiEditSchema, {
+    description: "For mode=edit: targeted text replacements (oldText→newText). Page must exist.",
+  })),
+});
+
+export const WikiWriteParams = Type.Object({
+  pages: Type.Array(WikiWritePageSchema, {
+    description: "Pages to write or update",
+  }),
+  // DEPRECATED: indexContent is ignored. Index is auto-rebuilt from all pages on disk.
+  // Kept in schema to avoid breaking existing callers.
+  indexContent: Type.Optional(
+    Type.String({ description: "Updated index.md content (full replacement)" }),
+  ),
+  logSummary: Type.Optional(
+    Type.String({ description: "One-line summary for log.md" }),
+  ),
+});
+
+export const WikiEditParams = Type.Object({
+  path: Type.String({ description: "Existing page path (e.g. 'resources/ssl-cert-gotchas')" }),
+  edits: Type.Array(WikiEditSchema, {
+    description: "Atomic exact text replacements. Every oldText must appear exactly once or no changes are written.",
+  }),
+  title: Type.Optional(Type.String({ description: "Optional replacement page title" })),
+  scope: Type.Optional(Type.Array(Type.String(), { description: "Optional replacement scope tags" })),
+  tags: Type.Optional(Type.Array(Type.String(), { description: "Optional replacement topic tags" })),
+  logSummary: Type.Optional(Type.String({ description: "One-line summary for log.md" })),
+});
+
+export const WikiReadParams = Type.Object({
+  path: Type.String({
+    description: "Page path (e.g. 'projects/auth-refactor') or page title",
+  }),
+});
+
+export const WikiMoveParams = Type.Object({
+  path: Type.String({
+    description: "Current page path (e.g. 'projects/auth-refactor')",
+  }),
+  to: PARA_ENUM,
+});
+
+export const WikiLintParams = Type.Object({
+  autoFix: Type.Optional(
+    Type.Boolean({ description: "Auto-fix simple issues (default true)" }),
+  ),
+});
+
+export const WikiMigrateParams = Type.Object({});
+
+export const WikiSummarizeParams = Type.Object({
+  target: Type.String({
+    description: "Page path, category name (e.g. 'projects'), or 'all'",
+  }),
+  depth: Type.Optional(
+    StringEnum(["brief", "detailed"] as const, {
+      description: "Summary depth (default brief)",
+    }),
+  ),
+});
+
+// -- Detail types for tool results -------------------------------------------
+
+export interface WikiIngestDetails {
+  sourceType: "url" | "file" | "text";
+  rawPath?: string;
+  sourceLength: number;
+}
+
+export interface WikiQueryDetails {
+  resultCount: number;
+  scopeUsed: string;
+}
+
+export interface WikiWriteDetails {
+  pagesWritten: string[];
+  indexUpdated: boolean;
+  logAppended: boolean;
+  pagesSkipped?: string[];
+}
+
+export interface WikiReadDetails {
+  found: boolean;
+  path?: string;
+}
+
+export interface WikiMoveDetails {
+  from: string;
+  to: string;
+}
+
+export interface WikiLintDetails {
+  issueCount: number;
+  fixedCount: number;
+  stats: LintReport["stats"];
+}
+
+export interface WikiSummarizeDetails {
+  target: string;
+  pageCount: number;
+}

package/src/tools/shared.ts

@@ -0,0 +1,35 @@
+import type { QMDStore } from "qmd-engine";
+import { enqueueWikiMaintenance } from "../scheduler/index.js";
+import { PARA_CATEGORIES, type ParaCategory } from "../wiki.js";
+
+// -- Source resolution helpers -----------------------------------------------
+
+/** Resolve a page path like "projects/auth-refactor" into category + slug. */
+export function parsePagePath(
+  path: string,
+): { category: ParaCategory; slug: string } | null {
+  const parts = path.split("/");
+  if (parts.length === 2) {
+    const cat = parts[0] as ParaCategory;
+    if (PARA_CATEGORIES.includes(cat)) {
+      const slug = parts[1].replace(/\.md$/, "");
+      return { category: cat, slug };
+    }
+  }
+  return null;
+}
+
+// -- Background maintenance --------------------------------------------------
+
+/**
+ * Schedule index rebuild + QMD reindex after latency-sensitive edits.
+ * Debounced per wiki directory and coordinated through the scheduler queue so
+ * multiple Pi processes do not run the same maintenance task concurrently.
+ */
+export function scheduleWikiMaintenance(
+  wikiDir: string,
+  store: QMDStore,
+  markDirty: () => void,
+): void {
+  enqueueWikiMaintenance(wikiDir, store, markDirty);
+}

package/src/tools/summarize.ts

@@ -0,0 +1,89 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ProjectScope } from "../scope.js";
+import { generateOverviewPrompt } from "../summarize.js";
+import { listPages, readPage, PARA_CATEGORIES, type ParaCategory, type WikiPage } from "../wiki.js";
+import type { WikiSummarizeDetails } from "./schemas.js";
+import { parsePagePath } from "./shared.js";
+
+// -- Factory: wiki_summarize execute -----------------------------------------
+
+export function createSummarizeExecute(
+  wikiDir: string,
+  getScope: () => ProjectScope,
+) {
+  return async (
+    params: { target: string; depth?: "brief" | "detailed" },
+  ): Promise<AgentToolResult<WikiSummarizeDetails>> => {
+    const scope = getScope();
+    const pages: WikiPage[] = [];
+
+    if (params.target === "all") {
+      // Summarize entire wiki
+      const refs = await listPages(wikiDir);
+      for (const ref of refs) {
+        const page = await readPage(wikiDir, ref.category, ref.slug);
+        if (page) pages.push(page);
+      }
+    } else if (PARA_CATEGORIES.includes(params.target as ParaCategory)) {
+      // Summarize a category
+      const refs = await listPages(wikiDir, params.target as ParaCategory);
+      for (const ref of refs) {
+        const page = await readPage(wikiDir, ref.category, ref.slug);
+        if (page) pages.push(page);
+      }
+    } else {
+      // Summarize a single page
+      const parsed = parsePagePath(params.target);
+      if (parsed) {
+        const page = await readPage(wikiDir, parsed.category, parsed.slug);
+        if (page) pages.push(page);
+      } else {
+        // Try finding by slug alone across categories
+        const allPages = await listPages(wikiDir);
+        const targetLower = params.target.toLowerCase();
+        for (const ref of allPages) {
+          if (ref.slug === targetLower || ref.title.toLowerCase() === targetLower) {
+            const page = await readPage(wikiDir, ref.category, ref.slug);
+            if (page) pages.push(page);
+            break;
+          }
+        }
+      }
+    }
+
+    if (pages.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No pages found for target "${params.target}". Nothing to summarize.`,
+          },
+        ],
+        details: { target: params.target, pageCount: 0 },
+      };
+    }
+
+    // Generate a bounded overview prompt for the LLM. For large targets like
+    // `all`, brief mode must not dump every full page body into model context.
+    const depth = params.depth ?? "brief";
+    const overviewPrompt = generateOverviewPrompt(pages, scope, { depth });
+    const depthNote =
+      depth === "detailed"
+        ? "\nProvide a DETAILED summary with full Key Facts, Insights, and Connections for each theme."
+        : "\nProvide a BRIEF overview — one paragraph per theme, focus on high-level patterns.";
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: overviewPrompt + depthNote +
+            "\n\nYou may optionally create a summary page via wiki_write if the overview is worth preserving.",
+        },
+      ],
+      details: {
+        target: params.target,
+        pageCount: pages.length,
+      },
+    };
+  };
+}

package/src/tools/write.ts

@@ -0,0 +1,252 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { QMDStore } from "qmd-engine";
+import type { ProjectScope } from "../scope.js";
+import { normalizeTags, normalizeScopes } from "../tag-registry.js";
+import { redactSecrets } from "../redact.js";
+import { autoLinkSlugs, syncFrontmatterLinks } from "../link-utils.js";
+import { validateFrontmatter } from "../frontmatter.js";
+import { appendLog, gitCommit, listPageSlugs, readPage, rebuildIndex, writePage, type ParaCategory, type WikiPage } from "../wiki.js";
+import type { WikiWriteDetails } from "./schemas.js";
+import { scheduleWikiMaintenance } from "./shared.js";
+
+// -- Factory: wiki_write execute ---------------------------------------------
+
+export function createWriteExecute(
+  wikiDir: string,
+  store: QMDStore,
+  getScope: () => ProjectScope,
+  markDirty: () => void,
+) {
+  return async (
+    params: {
+      pages: Array<{
+        category: ParaCategory;
+        slug: string;
+        title: string;
+        scope: string[];
+        tags: string[];
+        body: string;
+        mode: "create" | "replace" | "append" | "edit";
+        edits?: Array<{ oldText: string; newText: string }>;
+      }>;
+      indexContent?: string;
+      logSummary?: string;
+    },
+  ): Promise<AgentToolResult<WikiWriteDetails>> => {
+    const pagesWritten: string[] = [];
+    const pagesSkipped: string[] = [];
+    const now = new Date().toISOString();
+    const scope = getScope();
+
+    // Gather all existing slugs for auto-linking (slug-only readdir scan;
+    // reading/parsing every page here made wiki_write scale poorly)
+    const allSlugs = await listPageSlugs(wikiDir);
+
+    for (const pageSpec of params.pages) {
+      // Sanitize slug
+      const slug = pageSpec.slug
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+
+      if (!slug) {
+        continue; // skip invalid slugs
+      }
+
+      const existing = await readPage(wikiDir, pageSpec.category, slug);
+      const pagePath = `${pageSpec.category}/${slug}`;
+
+      // Track this slug for auto-linking other pages in this batch
+      allSlugs.add(slug);
+
+      if (pageSpec.mode === "create" && existing) {
+        pagesSkipped.push(`${pagePath} (already exists; use mode=replace, mode=append, or wiki_edit)`);
+        continue;
+      }
+
+      if (pageSpec.mode === "edit" && !existing) {
+        pagesSkipped.push(`${pagePath} (missing; wiki_write mode=edit requires an existing page)`);
+        continue;
+      }
+
+      if (pageSpec.mode === "edit" && existing) {
+        // Legacy edit mode: keep for compatibility, but make it atomic like wiki_edit.
+        const edits = pageSpec.edits ?? [];
+        if (edits.length === 0) {
+          continue; // no edits to apply
+        }
+        const errors: string[] = [];
+        for (const edit of edits) {
+          const first = existing.body.indexOf(edit.oldText);
+          const last = existing.body.lastIndexOf(edit.oldText);
+          if (first === -1) {
+            errors.push(`oldText not found: "${edit.oldText.slice(0, 60)}..."`);
+          } else if (first !== last) {
+            errors.push(`oldText is not unique: "${edit.oldText.slice(0, 60)}..."`);
+          }
+        }
+        if (errors.length > 0) {
+          pagesSkipped.push(`${pagePath} (${errors.join("; ")})`);
+          continue;
+        }
+        let editedBody = existing.body;
+        for (const edit of edits) {
+          editedBody = editedBody.replace(edit.oldText, edit.newText);
+        }
+        const linkedBody = redactSecrets(autoLinkSlugs(editedBody, allSlugs, slug)).text;
+        const rawScope = pageSpec.scope.length > 0 ? pageSpec.scope : existing.frontmatter.scope;
+        const newScope = normalizeScopes(rawScope);
+        const newTags = pageSpec.tags.length > 0 ? pageSpec.tags : existing.frontmatter.tags;
+        const updatedPage: WikiPage = {
+          category: pageSpec.category,
+          slug,
+          frontmatter: {
+            ...existing.frontmatter,
+            title: pageSpec.title || existing.frontmatter.title,
+            scope: newScope,
+            tags: normalizeTags(newTags, newScope),
+            updated: now,
+            links: syncFrontmatterLinks(linkedBody),
+          },
+          body: linkedBody,
+        };
+        await writePage(wikiDir, updatedPage);
+        pagesWritten.push(pagePath + (errors.length > 0 ? ` (${errors.length} edit(s) failed)` : ""));
+      } else if (pageSpec.mode === "append" && existing) {
+        // Append to existing page body
+        const combinedBody = existing.body.trimEnd() + "\n\n" + pageSpec.body;
+        const linkedBody = redactSecrets(autoLinkSlugs(combinedBody, allSlugs, slug)).text;
+        const mergedTags = [...new Set([...existing.frontmatter.tags, ...pageSpec.tags])];
+        const mergedScope = normalizeScopes([...new Set([...existing.frontmatter.scope, ...pageSpec.scope])]);
+        const updatedPage: WikiPage = {
+          ...existing,
+          body: linkedBody,
+          frontmatter: {
+            ...existing.frontmatter,
+            updated: now,
+            tags: normalizeTags(mergedTags, mergedScope),
+            scope: mergedScope,
+            links: syncFrontmatterLinks(linkedBody),
+          },
+        };
+        await writePage(wikiDir, updatedPage);
+        pagesWritten.push(pagePath);
+      } else if (pageSpec.mode === "replace" && existing) {
+        // Replace existing page body, update frontmatter
+        const linkedBody = redactSecrets(autoLinkSlugs(pageSpec.body, allSlugs, slug)).text;
+        const rawScope = pageSpec.scope.length > 0 ? pageSpec.scope : existing.frontmatter.scope;
+        const newScope = normalizeScopes(rawScope);
+        const newTags = pageSpec.tags.length > 0 ? pageSpec.tags : existing.frontmatter.tags;
+        const updatedPage: WikiPage = {
+          category: pageSpec.category,
+          slug,
+          frontmatter: {
+            ...existing.frontmatter,
+            title: pageSpec.title,
+            para: pageSpec.category,
+            scope: newScope,
+            tags: normalizeTags(newTags, newScope),
+            updated: now,
+            links: syncFrontmatterLinks(linkedBody),
+          },
+          body: linkedBody,
+        };
+        await writePage(wikiDir, updatedPage);
+        pagesWritten.push(pagePath);
+      } else {
+        // Create new page (or mode=create/replace on non-existing)
+        const linkedBody = redactSecrets(autoLinkSlugs(pageSpec.body, allSlugs, slug)).text;
+        const rawScope = pageSpec.scope.length > 0 ? pageSpec.scope : [scope.name];
+        const newScope = normalizeScopes(rawScope);
+        const frontmatter = validateFrontmatter({
+          title: pageSpec.title,
+          para: pageSpec.category,
+          scope: newScope,
+          tags: normalizeTags(pageSpec.tags, newScope),
+          sources: [],
+          created: now,
+          updated: now,
+          links: syncFrontmatterLinks(linkedBody),
+        });
+
+        const newPage: WikiPage = {
+          category: pageSpec.category,
+          slug,
+          frontmatter,
+          body: linkedBody,
+        };
+        await writePage(wikiDir, newPage);
+        pagesWritten.push(pagePath);
+      }
+    }
+
+    // Always auto-rebuild index from disk.
+    // The LLM's indexContent is unreliable — it only knows about pages
+    // in its context, so it produces partial indexes that overwrite
+    // the full one. indexContent parameter is deprecated and ignored.
+    let indexUpdated = false;
+    if (pagesWritten.length > 0) {
+      await rebuildIndex(wikiDir);
+      indexUpdated = true;
+    }
+
+    // Append to log.md if summary provided
+    let logAppended = false;
+    if (params.logSummary && pagesWritten.length > 0) {
+      await appendLog(wikiDir, {
+        date: now.split("T")[0],
+        operation: "ingest",
+        summary: params.logSummary,
+        pages: pagesWritten,
+      });
+      logAppended = true;
+    }
+
+    // Defer QMD BM25 reindex to the debounced background maintenance queue
+    // (same as wiki_edit). Immediate post-write queries are safe: queryWiki
+    // retries with a fresh store.update() before returning zero results.
+    if (pagesWritten.length > 0) {
+      scheduleWikiMaintenance(wikiDir, store, markDirty);
+    }
+
+    // Mark context cache dirty so before_agent_start rebuilds
+    markDirty();
+
+    // Git auto-commit
+    if (pagesWritten.length > 0) {
+      const commitMsg = params.logSummary
+        ? params.logSummary
+        : `wiki: ${pagesWritten.join(", ")}`;
+      await gitCommit(wikiDir, commitMsg);
+    }
+
+    const summary = [
+      pagesWritten.length > 0
+        ? `Wrote ${pagesWritten.length} page(s): ${pagesWritten.join(", ")}`
+        : "No pages written.",
+      pagesSkipped.length > 0 ? `Skipped ${pagesSkipped.length} page(s): ${pagesSkipped.join(", ")}` : "",
+    ].filter(Boolean).join("\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            summary,
+            indexUpdated ? "Updated index.md." : "",
+            logAppended ? `Logged: ${params.logSummary}` : "",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        },
+      ],
+      details: {
+        pagesWritten,
+        indexUpdated,
+        logAppended,
+        pagesSkipped,
+      },
+    };
+  };
+}