pi-weave 0.2.3 → 0.3.0

package/src/pi/tools/noteTool.ts

@@ -1,133 +1,22 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { join } from "node:path";
 import { Type } from "typebox";
 import {
-  addNote,
-  appendToNote,
-  extractRawTail,
-  finalizeNote,
-  formatNote,
+  executeNoteAction,
   formatRawAppend,
-  getNote,
-  listNotes,
-  NOTES_DIR,
-  repairVaultLinks,
-  resolveNotePath,
-  withMutationQueue,
-  resolveVaultRoot,
-  searchNotes,
-  suggestLinks,
-  readVault,
-  type LinkRepairResult,
-  type SuggestionReport,
+  WEAVE_NOTE_DESCRIPTION,
 } from "../../core";
 
-/** Cap on how many rows of each link-audit category get printed. */
-const LINK_REPORT_CAP = 20;
-
-/** Cap on notes printed by `list`; `details.notes` still carries them all. */
-const LIST_CAP = 50;
-
-function capped<T>(items: readonly T[], render: (item: T) => string): string[] {
-  const lines = items.slice(0, LINK_REPORT_CAP).map(render);
-  if (items.length > LINK_REPORT_CAP) lines.push(`  … and ${items.length - LINK_REPORT_CAP} more`);
-  return lines;
-}
-
-/**
- * Render suggestions as the text the model reads.
- *
- * Every row carries the shared terms that earned it. A bare score is
- * unreviewable; the evidence is what lets a human accept or reject a
- * suggestion without opening both notes.
- */
-function formatSuggestions(report: SuggestionReport, focus: string | undefined): string {
-  if (report.suggestions.length === 0) {
-    return focus === undefined
-      ? `No unlinked notes share enough distinctive vocabulary to suggest a connection (${report.considered} note(s) considered).`
-      : `Nothing unlinked looks related to '${focus}' (${report.considered} note(s) considered).`;
-  }
-  const head = focus === undefined
-    ? `${report.suggestions.length} suggested connection(s) across ${report.considered} note(s):`
-    : `${report.suggestions.length} note(s) look related to '${focus}':`;
-  const rows = report.suggestions.map((s) => {
-    const pair = focus === undefined ? `${s.a} ↔ ${s.b}` : s.a === focus ? s.b : s.a;
-    return `  ${s.score.toFixed(3)}  ${pair}\n         shared: ${s.shared.join(", ")}`;
-  });
-  return [
-    head,
-    ...rows,
-    "",
-    "These are suggestions, not links — nothing was written. Add a [[wikilink]] to any pair worth keeping.",
-  ].join("\n");
-}
-
-/** Render a link audit (and any repair) as the text the model reads. */
-function formatLinkReport(result: LinkRepairResult, applied: boolean): string {
-  const { audit } = result;
-  const stale = audit.total - audit.resolved;
-  // Occurrences, not rows. `total`/`resolved` count every `[[…]]` in the
-  // vault, while `fixable`/`unresolvable` are grouped (per note+target, per
-  // target). Reporting "70 stale" beside "40 unresolvable" with no unit
-  // invites the reader to subtract them and find 30 phantom links; saying
-  // what each number counts is the whole fix.
-  const lines = [
-    `${audit.total} wiki-link(s): ${audit.resolved} resolved, ${stale} stale.`,
-  ];
-  if (applied) {
-    lines.push(
-      result.applied.length === 0
-        ? "Nothing to repair automatically."
-        : `Repaired ${result.applied.length} link(s) across ${result.notes.length} note(s):`,
-      ...capped(result.applied, (f) => `  ${f.slug}: [[${f.from}]] → [[${f.to}]] (${f.rule})`),
-    );
-  } else if (audit.fixable.length > 0) {
-    lines.push(
-      `${audit.fixable.length} auto-fixable (re-run with fix: true):`,
-      ...capped(audit.fixable, (f) => `  ${f.slug}: [[${f.from}]] → [[${f.to}]] (${f.rule})`),
-    );
-  }
-  if (audit.ambiguous.length > 0) {
-    lines.push(
-      `${audit.ambiguous.length} ambiguous link(s) (several candidates — pick one and edit the note):`,
-      ...capped(audit.ambiguous, (a) => `  ${a.slug}: [[${a.target}]] → ${a.candidates.join(" | ")}`),
-    );
-  }
-  if (audit.unresolvable.length > 0) {
-    lines.push(
-      `${audit.unresolvable.length} unresolvable target(s) (no such note — write it or drop the link):`,
-      ...capped(audit.unresolvable, (u) => `  [[${u.target}]] ← ${u.notes.join(", ")}`),
-    );
-  }
-  if (audit.fixable.length === 0 && audit.ambiguous.length === 0 && audit.unresolvable.length === 0) {
-    lines.push("Every link resolves.");
-  }
-  return lines.join("\n");
-}
-
-/**
- * `weave_note` — the smart-notepad tool (design §1: vault knowledge).
- *
- * The LLM uses this to remember decisions, facts, and preferences as plain
- * Markdown notes that humans can read and edit directly on disk.
- */
+/** `weave_note` — the smart-notepad tool (design §1: vault knowledge). */
 export function registerNoteTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "weave_note",
     label: "Weave Note",
-    description:
-      "Read and write notes in the pi-weave vault — a persistent, human-readable knowledge base " +
-      "of Markdown notes. Actions: list (all notes — avoid on large vaults, prefer search), get (one note by slug), add (new note), " +
-      "append (extend a note; raw=true appends verbatim dictation into the ## Raw tail), " +
-      "finalize (restructure a note above its raw tail), search (title/tags/body), " +
-      "links (audit stale [[wiki-links]]; fix=true repairs the unambiguous ones), " +
-      "suggest (rank unlinked notes that share distinctive vocabulary; reports only, never writes). " +
-      "Use it to remember decisions, facts, and user preferences across sessions.",
+    description: WEAVE_NOTE_DESCRIPTION,
     promptSnippet: "Remember and retrieve durable knowledge in the pi-weave vault",
     promptGuidelines: [
       "Use weave_note to store durable knowledge (decisions, preferences, key facts) that should survive the session, marking source as agent-written knowledge.",
-      "Use weave_note with action=search before answering questions about past decisions, people, or projects; generated notes under sessions/ carry takeaways from earlier sessions.",
+      "Use weave_note with action=get when the slug is known; otherwise use one targeted action=search before answering questions about past decisions, people, or projects. A resolved search already contains the full note; do not fetch it again or retry with reformulated queries.",
       "Use weave_note with action=links to find and repair stale [[wiki-links]] deterministically instead of rereading the vault to reconnect notes by hand; add fix=true to apply the unambiguous repairs.",
       "Use weave_note with action=suggest to discover notes that belong together but are not linked (optionally scoped to one slug); it only reports — propose the links to the user rather than writing them.",
     ],
@@ -143,186 +32,9 @@ export function registerNoteTool(pi: ExtensionAPI): void {
       fix: Type.Optional(Type.Boolean({ description: "links: apply the unambiguous repairs. Omit for a read-only report" })),
       limit: Type.Optional(Type.Number({ description: "suggest: how many suggestions to return (default 20)" })),
     }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const vault = resolveVaultRoot();
-
-      switch (params.action) {
-        case "list": {
-          const notes = await listNotes(vault);
-          if (notes.length === 0) {
-            return {
-              content: [{ type: "text", text: `The vault at ${vault} has no notes yet.` }],
-              details: { action: "list", notes: [] },
-            };
-          }
-          // Truncated, because the whole list is rarely the answer and on a
-          // large vault it is actively harmful: hundreds of lines of slugs
-          // crowd out the conversation that prompted the call. Newest first
-          // (`listNotes` order), so the cap keeps what is most likely wanted,
-          // and the footer names `search` — the action that answers "is there
-          // a note about X" without reading the vault aloud.
-          const shown = notes.slice(0, LIST_CAP);
-          const lines = shown.map(
-            (n) => `- ${n.slug}: ${n.title}${n.tags.length > 0 ? ` [${n.tags.join(", ")}]` : ""} (updated ${n.updated}, source: ${n.source})`,
-          );
-          if (notes.length > shown.length) {
-            lines.push(
-              `… and ${notes.length - shown.length} more (newest ${shown.length} shown) — use action=search to find a specific note.`,
-            );
-          }
-          return {
-            content: [{ type: "text", text: `${notes.length} note(s) in ${vault}:\n${lines.join("\n")}` }],
-            details: { action: "list", notes },
-          };
-        }
-
-        case "get": {
-          if (!params.slug) throw new Error("weave_note(get) requires 'slug'");
-          const note = await getNote(vault, params.slug);
-          if (!note) {
-            return { content: [{ type: "text", text: `No note found with slug '${params.slug}'.` }], details: { action: "get", found: false } };
-          }
-          return { content: [{ type: "text", text: formatNote(note) }], details: { action: "get", found: true, note } };
-        }
-
-        case "add": {
-          if (!params.title) throw new Error("weave_note(add) requires 'title'");
-          if (!params.text) throw new Error("weave_note(add) requires 'text'");
-          const title = params.title;
-          const text = params.text;
-          // Serialized per vault: parallel adds of the same title must not
-          // race the unique-slug check and overwrite each other.
-          const note = await withMutationQueue(join(vault, NOTES_DIR), () =>
-            addNote(vault, {
-              title,
-              body: text,
-              ...(params.tags ? { tags: params.tags } : {}),
-              ...(params.source ? { source: params.source } : {}),
-            }),
-          );
-          return {
-            content: [{ type: "text", text: `Note created: ${note.slug} (${vault})` }],
-            details: { action: "add", note },
-          };
-        }
-
-        case "append": {
-          if (!params.slug) throw new Error("weave_note(append) requires 'slug'");
-          if (!params.text) throw new Error("weave_note(append) requires 'text'");
-          const slug = params.slug;
-          const text = params.text;
-          const path = resolveNotePath(vault, slug);
-          if (!path) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: `Invalid note slug '${slug}' — notes are flat files inside the vault (no path separators or '..').`,
-                },
-              ],
-              details: { action: "append", found: false },
-            };
-          }
-          // Serialized read-modify-write: parallel weave_note appends (and
-          // pi's own file tools) targeting the same note would otherwise
-          // lose each other's additions.
-          const note = await withMutationQueue(path, () =>
-            appendToNote(vault, slug, text, new Date(), params.raw ? { raw: true } : {}),
-          );
-          if (!note) {
-            return { content: [{ type: "text", text: `No note found with slug '${params.slug}'.` }], details: { action: "append", found: false } };
-          }
-          return {
-            content: [{ type: "text", text: params.raw ? `Appended verbatim to the ## Raw tail of ${note.slug} (updated ${note.updated}).` : `Appended to ${note.slug} (updated ${note.updated}).` }],
-            details: { action: "append", found: true, note },
-          };
-        }
-
-        case "finalize": {
-          if (!params.slug) throw new Error("weave_note(finalize) requires 'slug'");
-          if (!params.text) throw new Error("weave_note(finalize) requires 'text'");
-          const slug = params.slug;
-          const text = params.text;
-          const path = resolveNotePath(vault, slug);
-          if (!path) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: `Invalid note slug '${slug}' — notes are flat files inside the vault (no path separators or '..').`,
-                },
-              ],
-              details: { action: "finalize", found: false },
-            };
-          }
-          // Serialized read-modify-write, same as append: finalize replaces the
-          // body above the raw tail, so it must not race other writers.
-          const note = await withMutationQueue(path, () => finalizeNote(vault, slug, { body: text }));
-          if (!note) {
-            return { content: [{ type: "text", text: `No note found with slug '${params.slug}'.` }], details: { action: "finalize", found: false } };
-          }
-          // Be truthful about what was preserved: a note with no `## Raw`
-          // marker yet gets its whole pre-finalize body preserved as a new
-          // raw tail (never silently dropped).
-          const preserved = extractRawTail(note.body) !== "";
-          return {
-            content: [{ type: "text", text: `Finalized ${note.slug} (updated ${note.updated}). ${preserved ? "Raw tail preserved beneath the structured body." : "Note body was empty — nothing to preserve."}` }],
-            details: { action: "finalize", found: true, note },
-          };
-        }
-
-        case "search": {
-          if (!params.query) throw new Error("weave_note(search) requires 'query'");
-          const hits = await searchNotes(vault, params.query);
-          if (hits.length === 0) {
-            return {
-              content: [{ type: "text", text: `No notes matched '${params.query}'.` }],
-              details: { action: "search", hits: [] },
-            };
-          }
-          const lines = hits.map(
-            (h) => `- ${h.summary.slug}: ${h.summary.title} (score ${h.score})\n  ${h.snippet}`,
-          );
-          return {
-            content: [{ type: "text", text: `${hits.length} hit(s) for '${params.query}':\n${lines.join("\n")}` }],
-            details: { action: "search", hits },
-          };
-        }
-
-        case "suggest": {
-          const { notes } = await readVault(vault);
-          const report = suggestLinks(
-            { notes },
-            {
-              ...(params.slug ? { slug: params.slug } : {}),
-              ...(params.limit !== undefined ? { limit: params.limit } : {}),
-            },
-          );
-          return {
-            content: [{ type: "text", text: formatSuggestions(report, params.slug) }],
-            details: { action: "suggest", considered: report.considered, suggestions: report.suggestions },
-          };
-        }
-
-        case "links": {
-          const apply = params.fix === true;
-          const result = await repairVaultLinks(vault, apply ? { apply: true } : {});
-          return {
-            content: [{ type: "text", text: formatLinkReport(result, apply) }],
-            details: {
-              action: "links",
-              fixed: apply,
-              total: result.audit.total,
-              resolved: result.audit.resolved,
-              fixable: result.audit.fixable,
-              ambiguous: result.audit.ambiguous,
-              unresolvable: result.audit.unresolvable,
-              applied: result.applied,
-              notes: result.notes,
-            },
-          };
-        }
-      }
+    async execute(_toolCallId, params) {
+      const result = await executeNoteAction(params);
+      return { content: [{ type: "text", text: result.text }], details: result.details };
     },
   });
 }

package/src/pi/tools/repoTool.ts

@@ -1,31 +1,14 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import {
-  assessStaleness,
-  buildRepoIndex,
-  findGitRoot,
-  readRepoIndex,
-  repoIndexDir,
-  summarizeIndex,
-  writeRepoIndex,
-} from "../../core";
+import { executeRepoAction, WEAVE_REPO_DESCRIPTION } from "../../core";
 
-/**
- * `weave_repo` — the repository-exploration tool (design §2/§8).
- *
- * Builds and reads the derived .okf index: structure, modules, packages,
- * entry points, plus git-aware staleness.
- */
+/** `weave_repo` — the repository-exploration tool (design §2/§8). */
 export function registerRepoTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "weave_repo",
     label: "Weave Repo",
-    description:
-      "Explore the current git repository through its pi-weave knowledge index (.okf). " +
-      "Actions: status (index freshness vs git state), scan (build/refresh the index), " +
-      "overview (read the indexed structure: languages, packages, modules, entry points). " +
-      "The index is derived and rebuildable; scanning is always safe.",
+    description: WEAVE_REPO_DESCRIPTION,
     promptSnippet: "Explore the repository's structure via its .okf knowledge index",
     promptGuidelines: [
       "Use weave_repo action=overview to learn repository structure before broad code exploration instead of scanning files one by one.",
@@ -34,61 +17,11 @@ export function registerRepoTool(pi: ExtensionAPI): void {
     parameters: Type.Object({
       action: StringEnum(["status", "scan", "overview"] as const),
     }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const root = await findGitRoot(ctx.cwd);
-      if (!root) {
-        return {
-          content: [{ type: "text", text: "Not inside a git repository — repository knowledge is unavailable here." }],
-          details: { action: params.action, inRepo: false },
-        };
-      }
-
-      switch (params.action) {
-        case "status": {
-          const staleness = await assessStaleness(root);
-          const index = staleness.state !== "missing" ? await readRepoIndex(root) : null;
-          const lines = [`Index state: ${staleness.state}`];
-          for (const reason of staleness.reasons) lines.push(`- ${reason}`);
-          if (index) lines.push(`Indexed at: ${index.updated} by ${index.generator}`);
-          return {
-            content: [{ type: "text", text: `Repository ${root}\n${lines.join("\n")}` }],
-            details: { action: "status", inRepo: true, staleness, indexed: index !== null },
-          };
-        }
-
-        case "scan": {
-          onUpdate?.({ content: [{ type: "text", text: `Scanning ${root}…` }], details: {} });
-          const index = await buildRepoIndex(root);
-          if (!index) {
-            return {
-              content: [{ type: "text", text: "Cannot build index: the repository has no commits yet." }],
-              details: { action: "scan", inRepo: true, scanned: false },
-            };
-          }
-          const dir = await writeRepoIndex(root, index);
-          const summary = summarizeIndex(index).join("\n");
-          return {
-            content: [{ type: "text", text: `Knowledge index written to ${dir}\n\n${summary}` }],
-            details: { action: "scan", inRepo: true, scanned: true, index },
-          };
-        }
-
-        case "overview": {
-          const index = await readRepoIndex(root);
-          if (!index) {
-            return {
-              content: [{ type: "text", text: `No knowledge index at ${repoIndexDir(root)} yet. Use action=scan to build one.` }],
-              details: { action: "overview", inRepo: true, indexed: false },
-            };
-          }
-          const staleness = await assessStaleness(root);
-          const header = staleness.state === "fresh" ? "" : `⚠ index is ${staleness.state} (consider rescanning)\n`;
-          return {
-            content: [{ type: "text", text: header + summarizeIndex(index).join("\n") }],
-            details: { action: "overview", inRepo: true, indexed: true, staleness, index },
-          };
-        }
-      }
+    async execute(_toolCallId, params, _signal, onUpdate, ctx) {
+      const result = await executeRepoAction(params, ctx.cwd, (text) => {
+        onUpdate?.({ content: [{ type: "text", text }], details: {} });
+      });
+      return { content: [{ type: "text", text: result.text }], details: result.details };
     },
   });
 }

package/src/pi/viewer/web/run.ts

@@ -33,43 +33,19 @@
  * run, rather than that some private function was called.
  */
 
-import { platform as osPlatform } from "node:os";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { resolveVaultRoot, WorkspaceCache } from "../../../core";
 import {
-  startWorkspaceServer,
-  type StartWorkspaceServerOptions,
-  type WorkspaceServer,
-} from "../../../web/server/server";
+  browserOpenCommand,
+  WorkspaceServerController,
+  type StartServerFn,
+  type WorkspaceServerSession,
+} from "../../../web/server/controller";
 
 /** The slice of `ExtensionAPI.exec` this module uses. */
 export type ExecFn = (command: string, args: string[]) => Promise<{ code: number; stderr: string }>;
 
-/** `startWorkspaceServer`, as a seam so tests can pin `idleMs` and the bundle. */
-export type StartServerFn = (opts: StartWorkspaceServerOptions) => Promise<WorkspaceServer>;
-
-/**
- * The command that hands a URL to the desktop's default browser.
- *
- * `os` is injectable so the whole mapping is unit-testable on any host
- * without stubbing globals — the same convention as `openNoteCommand`.
- */
-export function browserOpenCommand(
-  url: string,
-  os: NodeJS.Platform = osPlatform(),
-): { command: string; args: string[] } {
-  if (os === "darwin") return { command: "open", args: [url] };
-  // The empty string is `start`'s title argument. Without it, a URL that
-  // happens to be quoted is consumed as the window title and nothing opens.
-  if (os === "win32") return { command: "cmd", args: ["/c", "start", "", url] };
-  return { command: "xdg-open", args: [url] };
-}
-
-/** Everything one running workspace owns. Closed as a unit. */
-export interface WebWorkspaceSession {
-  server: WorkspaceServer;
-  cache: WorkspaceCache;
-}
+export { browserOpenCommand };
+export type WebWorkspaceSession = WorkspaceServerSession;
 
 export interface WebWorkspaceDeps {
   /** `ExtensionAPI.exec`. Used only to launch the browser. */
@@ -115,17 +91,20 @@ export interface RunWebOutcome {
  */
 export class WebWorkspaceController {
   private readonly deps: WebWorkspaceDeps;
-  private session: WebWorkspaceSession | null = null;
-  /** The single in-flight boot, so two fast `/weave-view`s do not race. */
-  private booting: Promise<WebWorkspaceSession> | null = null;
+  private readonly server: WorkspaceServerController;
 
   constructor(deps: WebWorkspaceDeps) {
     this.deps = deps;
+    this.server = new WorkspaceServerController({
+      ...(deps.startServer ? { startServer: deps.startServer } : {}),
+      ...(deps.vaultRoot ? { vaultRoot: deps.vaultRoot } : {}),
+      ...(deps.onStateChange ? { onStateChange: deps.onStateChange } : {}),
+    });
   }
 
   /** Bound port while a workspace is running, else `null`. Drives the status line. */
   port(): number | null {
-    return this.session?.server.port ?? null;
+    return this.server.port();
   }
 
   /**
@@ -136,9 +115,7 @@ export class WebWorkspaceController {
    * rather than a server they cannot find.
    */
   async run(ctx: ExtensionCommandContext, opts: RunWebOptions): Promise<RunWebOutcome> {
-    const existing = this.session;
-    const session = existing ?? (await this.boot(ctx));
-    const started = existing === null;
+    const { session, started } = await this.server.run(ctx.cwd);
 
     // Only a session with a UI has a browser worth spawning: over `--mode
     // rpc` or a plain SSH pipe there is no desktop on this side of the
@@ -154,45 +131,7 @@ export class WebWorkspaceController {
 
   /** Stop the workspace server. Idempotent. */
   async close(): Promise<void> {
-    // A close arriving mid-boot must still close what that boot produced,
-    // or `session_shutdown` during a slow start leaks the whole stack.
-    const booting = this.booting;
-    if (booting !== null) await booting.catch(() => undefined);
-    const session = this.session;
-    if (session === null) return;
-    this.session = null;
-    await session.server.close();
-    this.deps.onStateChange?.();
-  }
-
-  // --- internals --------------------------------------------------------------
-
-  private async boot(ctx: ExtensionCommandContext): Promise<WebWorkspaceSession> {
-    if (this.booting !== null) return this.booting;
-    const boot = this.bootOnce(ctx);
-    this.booting = boot;
-    try {
-      const session = await boot;
-      this.session = session;
-      this.deps.onStateChange?.();
-      return session;
-    } finally {
-      this.booting = null;
-    }
-  }
-
-  private async bootOnce(ctx: ExtensionCommandContext): Promise<WebWorkspaceSession> {
-    const cwd = ctx.cwd;
-    const vaultRoot = (this.deps.vaultRoot ?? resolveVaultRoot)();
-    const cache = new WorkspaceCache({ cwd, vaultRoot });
-    const startServer = this.deps.startServer ?? startWorkspaceServer;
-    const server = await startServer({
-      cwd,
-      vaultRoot,
-      cache,
-    });
-
-    return { server, cache };
+    await this.server.close();
   }
 
   /** Spawn the browser, reporting failure rather than throwing it. */