pi-weave 0.3.12 → 0.3.14

package/src/claude/sessions.ts

@@ -0,0 +1,158 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { hashContent, type SessionDigest } from "../core";
+import { digestFromMessages } from "../core/sessionDigest";
+
+/**
+ * Claude Code's own transcripts, mapped onto the shared session digest.
+ *
+ * Claude Code writes one JSONL file per session under
+ * `<config dir>/projects/<cwd with every non-alphanumeric as "-">/<session id>.jsonl`,
+ * where the config dir is `CLAUDE_CONFIG_DIR` or `~/.claude`.
+ * Each assistant content block is its own line; lines of one reply share
+ * `message.id`. Tool results come back as user lines holding `tool_result`
+ * blocks, and slash commands and `!` shell runs are user lines wrapped in
+ * tags. Everything else (attachments, titles, bookkeeping) is skipped.
+ */
+
+export function claudeConfigDir(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+  return env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+}
+
+export function claudeProjectDir(cwd: string, configDir: string = claudeConfigDir()): string {
+  return join(configDir, "projects", cwd.replace(/[^a-zA-Z0-9]/g, "-"));
+}
+
+/** The session's transcript, or this project's most recently written one. */
+export async function findTranscript(cwd: string, sessionId: string | undefined, configDir: string = claudeConfigDir()): Promise<string | null> {
+  const dir = claudeProjectDir(cwd, configDir);
+  if (sessionId) {
+    const path = join(dir, `${sessionId}.jsonl`);
+    if (await stat(path).then((info) => info.isFile(), () => false)) return path;
+  }
+  const names = await readdir(dir).catch(() => [] as string[]);
+  let newest: { path: string; mtime: number } | null = null;
+  for (const name of names) {
+    if (!name.endsWith(".jsonl")) continue;
+    const path = join(dir, name);
+    const info = await stat(path).catch(() => null);
+    if (info?.isFile() && (!newest || info.mtimeMs > newest.mtime)) newest = { path, mtime: info.mtimeMs };
+  }
+  return newest?.path ?? null;
+}
+
+export function transcriptSessionId(path: string): string {
+  return basename(path, ".jsonl");
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function blocks(content: unknown): Record<string, unknown>[] {
+  return Array.isArray(content) ? content.map(record) : [];
+}
+
+function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  return blocks(content).filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text as string).join("\n");
+}
+
+const tag = (text: string, name: string) => new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(text)?.[1]?.trim();
+
+/** A user line as the digest should see it: a prompt, a slash command, a shell run, or nothing. */
+function userMessage(text: string): Record<string, unknown> | null {
+  if (!text.trim()) return null;
+  if (text.includes("<bash-input>")) return { type: "shell" };
+  const command = tag(text, "command-name");
+  if (command) return { type: "user", text: [command, tag(text, "command-args")].filter(Boolean).join(" ") };
+  // Command echoes and shell output are the harness talking, not the user.
+  if (/^\s*<(local-command-|bash-std|command-message)/.test(text)) return null;
+  return { type: "user", text };
+}
+
+export interface ClaudeTranscript {
+  digest: SessionDigest;
+  /** Changes only when the conversation does, so an unchanged session is not re-summarized. */
+  hash: string;
+}
+
+export function parseClaudeTranscript(text: string, fallbackId = ""): ClaudeTranscript {
+  const entries: Record<string, unknown>[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(record(JSON.parse(line)));
+    } catch {
+      // A line cut off mid-write is expected while the session is live.
+    }
+  }
+  const failedTools = new Set<string>();
+  for (const entry of entries) {
+    for (const block of blocks(record(entry.message).content)) {
+      if (block.type === "tool_result" && block.is_error === true && typeof block.tool_use_id === "string") failedTools.add(block.tool_use_id);
+    }
+  }
+
+  let id = "";
+  let cwd = "";
+  let startedAt = "";
+  let endedAt = "";
+  let aiTitle: string | null = null;
+  let customTitle: string | null = null;
+  const messages: Record<string, unknown>[] = [];
+  const replies = new Map<string, Record<string, unknown>>();
+  for (const entry of entries) {
+    if (typeof entry.aiTitle === "string" && entry.aiTitle.trim()) aiTitle = entry.aiTitle.trim();
+    if (typeof entry.customTitle === "string" && entry.customTitle.trim()) customTitle = entry.customTitle.trim();
+    if (entry.type !== "user" && entry.type !== "assistant") continue;
+    if (entry.isSidechain === true) continue;
+    id ||= typeof entry.sessionId === "string" ? entry.sessionId : "";
+    cwd ||= typeof entry.cwd === "string" ? entry.cwd : "";
+    if (typeof entry.timestamp === "string") {
+      startedAt ||= entry.timestamp;
+      endedAt = entry.timestamp;
+    }
+    const message = record(entry.message);
+    if (entry.type === "user") {
+      if (entry.isMeta === true) continue;
+      const text = textOf(message.content);
+      if (entry.isCompactSummary === true) {
+        messages.push({ type: "compaction", summary: text });
+        continue;
+      }
+      const mapped = userMessage(text);
+      if (mapped) messages.push(mapped);
+      continue;
+    }
+    const key = typeof message.id === "string" ? message.id : `line-${messages.length}`;
+    let reply = replies.get(key);
+    if (!reply) {
+      const model = typeof message.model === "string" && message.model !== "<synthetic>" ? { providerID: "anthropic", id: message.model } : {};
+      reply = { type: "assistant", model, error: entry.isApiErrorMessage === true, content: [] };
+      replies.set(key, reply);
+      messages.push(reply);
+    }
+    const content = reply.content as Record<string, unknown>[];
+    for (const block of blocks(message.content)) {
+      if (block.type === "text") content.push({ type: "text", text: block.text });
+      if (block.type === "tool_use") {
+        content.push({ type: "tool", name: block.name, state: { status: failedTools.has(String(block.id)) ? "error" : "completed" } });
+      }
+    }
+  }
+  const digest = digestFromMessages({
+    id: id || fallbackId,
+    cwd,
+    parentSession: null,
+    startedAt,
+    endedAt: endedAt || startedAt,
+    name: customTitle ?? aiTitle,
+  }, messages);
+  return { digest, hash: hashContent(JSON.stringify(messages)) };
+}
+
+export async function readClaudeTranscript(path: string): Promise<ClaudeTranscript> {
+  return parseClaudeTranscript(await readFile(path, "utf8"), transcriptSessionId(path));
+}

package/src/core/index.ts

@@ -64,6 +64,9 @@ export {
   getNote,
   listNotes,
   moveNote,
+  moveHtmlArtifact,
+  renameHtmlArtifact,
+  deleteHtmlArtifact,
   parseHtmlArtifact,
   renameFolder,
   readVault,

package/src/core/sessionDigest.ts

@@ -0,0 +1,103 @@
+import type { SessionDigest } from "./sessions";
+
+/**
+ * One harness-neutral way to build a {@link SessionDigest}.
+ *
+ * Pi sessions are parsed from their own JSONL by `parseSessionDigest`. Every
+ * other harness (OpenCode's session API, Claude Code's transcripts) maps its
+ * records onto the small message shape below and lets this function do the
+ * counting, clipping and capping, so the digests stay identical in form.
+ *
+ * Messages are `unknown` on purpose: records come from outside the process,
+ * and anything malformed is skipped rather than trusted.
+ *
+ * - `{ type: "user", text }`
+ * - `{ type: "shell" }` — a direct shell execution by the user
+ * - `{ type: "compaction", summary }`
+ * - `{ type: "assistant", model: { providerID, id }, finish?, error?, content: [{ type: "text", text } | { type: "tool", name, state: { status } }] }`
+ */
+export interface DigestSessionInfo {
+  id: string;
+  cwd: string;
+  parentSession: string | null;
+  startedAt: string;
+  endedAt: string;
+  name: string | null;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" ? value as Record<string, unknown> : {};
+}
+
+function clipped(value: unknown, max: number): string {
+  if (typeof value !== "string") return "";
+  const text = value.trim();
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+
+export function digestFromMessages(info: DigestSessionInfo, messages: readonly unknown[]): SessionDigest {
+  const digest: SessionDigest = {
+    ...info,
+    models: [],
+    userCount: 0,
+    assistantCount: 0,
+    toolResultCount: 0,
+    errors: 0,
+    bashCount: 0,
+    tools: {},
+    firstUserMessage: null,
+    userMessages: [],
+    compactions: [],
+    branchSummaries: [],
+    lastAssistantText: null,
+  };
+  for (const raw of messages) {
+    const message = record(raw);
+    if (message.type === "user") {
+      digest.userCount += 1;
+      const text = clipped(message.text, 400);
+      if (text) {
+        digest.userMessages.push(text);
+        if (digest.userMessages.length > 60) digest.userMessages.shift();
+        digest.firstUserMessage ??= clipped(text, 120);
+      }
+      continue;
+    }
+    if (message.type === "shell") {
+      digest.bashCount += 1;
+      continue;
+    }
+    if (message.type === "compaction") {
+      const summary = clipped(message.summary, 1_200);
+      if (summary) {
+        digest.compactions.push(summary);
+        if (digest.compactions.length > 3) digest.compactions.shift();
+      }
+      continue;
+    }
+    if (message.type !== "assistant") continue;
+    digest.assistantCount += 1;
+    const model = record(message.model);
+    if (typeof model.providerID === "string" && typeof model.id === "string") {
+      const label = `${model.providerID}/${model.id}`;
+      if (!digest.models.includes(label)) digest.models.push(label);
+    }
+    if (message.finish === "error" || message.error) digest.errors += 1;
+    const content = Array.isArray(message.content) ? message.content : [];
+    const text = content
+      .filter((part) => record(part).type === "text")
+      .map((part) => record(part).text)
+      .filter((part): part is string => typeof part === "string")
+      .join("\n");
+    if (text.trim()) digest.lastAssistantText = clipped(text, 1_200);
+    for (const part of content) {
+      const tool = record(part);
+      if (tool.type !== "tool") continue;
+      digest.toolResultCount += 1;
+      const name = typeof tool.name === "string" ? tool.name : "unknown";
+      digest.tools[name] = (digest.tools[name] ?? 0) + 1;
+      if (record(tool.state).status === "error") digest.errors += 1;
+    }
+  }
+  return digest;
+}

package/src/core/tools.ts

@@ -0,0 +1,63 @@
+import { executeNoteAction, WEAVE_NOTE_DESCRIPTION, type NoteActionInput, type NoteActionResult } from "./noteAction";
+import { executeRepoAction, WEAVE_REPO_DESCRIPTION, type RepoActionInput } from "./repoAction";
+
+/**
+ * The `weave_note` and `weave_repo` tools, defined once for every harness.
+ *
+ * Plain JSON Schema, because that is the one format Pi, OpenCode and MCP
+ * (Claude Code) all accept. Each adapter only maps these definitions onto its
+ * own registration call and adds what is genuinely harness-specific, such as
+ * Pi's prompt guidelines.
+ */
+
+const noteInput = {
+  type: "object",
+  properties: {
+    action: { type: "string", enum: ["list", "get", "add", "append", "finalize", "search", "links", "suggest"] },
+    title: { type: "string", description: "Note title (add)" },
+    text: { type: "string", description: "Markdown body (add), addition (append), or restructured body above the raw tail (finalize)" },
+    tags: { type: "array", items: { type: "string" }, description: "Tags (add)" },
+    slug: { type: "string", description: "Note slug (get, append, finalize)" },
+    raw: {
+      type: "boolean",
+      description: "add/append: keep text as verbatim dictation in the ## Raw tail (timestamped fenced block; tail created if missing). Use for the user's own words, including the first words of a dictated note; omit for structured Markdown",
+    },
+    source: {
+      type: "string",
+      enum: ["human", "agent"],
+      description: "Provenance (add): human for user-scribbled notes, agent for agent-drafted (default agent)",
+    },
+    query: { type: "string", description: "Search query (search)" },
+    fix: { type: "boolean", description: "links: apply the unambiguous repairs. Omit for a read-only report" },
+    limit: { type: "number", description: "suggest: how many suggestions to return (default 20)" },
+  },
+  required: ["action"],
+  additionalProperties: false,
+} as const;
+
+const repoInput = {
+  type: "object",
+  properties: {
+    action: { type: "string", enum: ["overview"] },
+  },
+  required: ["action"],
+  additionalProperties: false,
+} as const;
+
+export const weaveTools = [
+  {
+    name: "weave_note",
+    description: WEAVE_NOTE_DESCRIPTION,
+    input: noteInput,
+    execute: (input: unknown, _cwd: string, _progress?: (text: string) => Promise<void>): Promise<NoteActionResult> =>
+      executeNoteAction(input as NoteActionInput),
+  },
+  {
+    name: "weave_repo",
+    description: WEAVE_REPO_DESCRIPTION,
+    input: repoInput,
+    execute: (input: unknown, cwd: string, _progress?: (text: string) => Promise<void>) => executeRepoAction(input as RepoActionInput, cwd),
+  },
+];
+
+export type WeaveTool = (typeof weaveTools)[number];

package/src/core/vault.ts

@@ -764,6 +764,80 @@ export async function moveNote(root: string, slug: string, folder: string | null
   });
 }
 
+/**
+ * Move a standalone HTML artifact to an existing vault folder, or to the vault
+ * root with `null`. Notes that link to it by path follow it, as they do a note.
+ */
+export async function moveHtmlArtifact(root: string, slug: string, folder: string | null): Promise<VaultMutationResult> {
+  const from = resolveHtmlPath(root, slug);
+  if (from === null) return { ok: false, reason: "invalid" };
+  const targetDir = folder === null ? join(root, NOTES_DIR) : resolveFolderPath(root, folder);
+  if (targetDir === null || !(await isDirectory(targetDir))) return { ok: false, reason: "missing" };
+  const target = folder === null ? basename(slug) : `${folder}/${basename(slug)}`;
+  const to = resolveHtmlPath(root, target)!;
+  return withVaultLock(root, async () => {
+    if (!(await exists(from))) return { ok: false, reason: "missing" };
+    if (from === to) return { ok: true, slug };
+    if (await exists(to)) return { ok: false, reason: "collision" };
+    await fs.rename(from, to);
+    await repointBacklinks(root, new Map([[slug, target]]));
+    return { ok: true, slug: target };
+  });
+}
+
+/**
+ * Rename a standalone HTML artifact in place. The new name sets the file name
+ * (slugified, extension kept) and the title the workspace shows, which lives
+ * in a leading `<!-- --- title: ... --- -->` comment or in `<title>`; a file
+ * with neither takes its title from the file name. Links follow the file.
+ */
+export async function renameHtmlArtifact(root: string, slug: string, name: string): Promise<VaultMutationResult> {
+  const from = resolveHtmlPath(root, slug);
+  const title = name.trim().replace(/\.html?$/i, "").trim();
+  if (from === null || title === "") return { ok: false, reason: "invalid" };
+  const ext = /\.html?$/i.exec(slug)![0];
+  const parent = slug.split("/").slice(0, -1).join("/");
+  const target = [...(parent === "" ? [] : [parent]), `${slugify(title)}${ext}`].join("/");
+  const to = resolveHtmlPath(root, target)!;
+  return withVaultLock(root, async () => {
+    let text: string;
+    try {
+      text = await fs.readFile(from, "utf8");
+    } catch {
+      return { ok: false, reason: "missing" };
+    }
+    if (from !== to && await exists(to)) return { ok: false, reason: "collision" };
+    await fs.writeFile(from, retitleHtml(text, title), "utf8");
+    if (from === to) return { ok: true, slug };
+    await fs.rename(from, to);
+    await repointBacklinks(root, new Map([[slug, target]]));
+    return { ok: true, slug: target };
+  });
+}
+
+/** Set the title `parseHtmlArtifact` reads, leaving every other byte alone. */
+function retitleHtml(text: string, title: string): string {
+  const comment = /<!--[\s\S]*?---\n([\s\S]*?)\n---[\s\S]*?-->/m.exec(text);
+  if (comment !== null && /^title:.*$/m.test(comment[1]!)) {
+    // `-->` would close the comment early.
+    const fields = comment[1]!.replace(/^title:.*$/m, () => `title: ${quoteField(title.replace(/-->/g, "->"))}`);
+    return text.slice(0, comment.index) + comment[0].replace(comment[1]!, () => fields) + text.slice(comment.index + comment[0].length);
+  }
+  const escaped = title.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return text.replace(/(<title\b[^>]*>)[\s\S]*?(<\/title>)/i, (_, open: string, close: string) => `${open}${escaped}${close}`);
+}
+
+/** Permanently delete one standalone HTML artifact. */
+export async function deleteHtmlArtifact(root: string, slug: string): Promise<VaultMutationResult> {
+  const path = resolveHtmlPath(root, slug);
+  if (path === null) return { ok: false, reason: "invalid" };
+  return withVaultLock(root, async () => {
+    if (!(await exists(path))) return { ok: false, reason: "missing" };
+    await fs.unlink(path);
+    return { ok: true };
+  });
+}
+
 /** Permanently delete one note. */
 export async function deleteNote(root: string, slug: string): Promise<VaultMutationResult> {
   const path = resolveNotePath(root, slug);
@@ -789,12 +863,12 @@ export async function renameFolder(root: string, folder: string, name: string):
     if (!(await isDirectory(from))) return { ok: false, reason: "missing" };
     if (from !== to && await exists(to)) return { ok: false, reason: "collision" };
     if (from === to) return { ok: true, path: target };
-    // Every note under the folder changes slug, so the whole subtree's
-    // backlinks move with it — collected before the rename, while the old
-    // paths still exist.
+    // Every note and HTML file under the folder changes slug, so the whole
+    // subtree's backlinks move with it — collected before the rename, while
+    // the old paths still exist. HTML slugs keep their extension.
     const moved = (await listNoteFiles(root))
-      .filter((f) => isMarkdown(f) && f.startsWith(`${folder}/`))
-      .map((f) => f.slice(0, -".md".length));
+      .filter((f) => f.startsWith(`${folder}/`))
+      .map((f) => isMarkdown(f) ? f.slice(0, -".md".length) : f);
     await fs.rename(from, to);
     await moveHistoryFolder(root, folder, target);
     await repointBacklinks(root, new Map(moved.map((s) => [s, `${target}/${s.slice(folder.length + 1)}`])));

package/src/core/view/tree.ts

@@ -273,8 +273,8 @@ export function treeRows(model: GraphModel, state: TreeState): TreeRow[] {
 export function treeEmptyHint(model: GraphModel): string | null {
   const vault = model.nodes.find((n) => n.kind === "vault");
   if (!vault) return null;
-  // no notes and no repository
-  const hasNotes = model.nodes.some((n) => n.kind === "note");
+  // nothing in the vault (no note, HTML file or folder) and no repository
+  const hasNotes = model.nodes.some((n) => n.kind === "note" || n.id.startsWith("artifact:") || n.id.startsWith("vfolder:"));
   const hasRepo = model.nodes.some((n) => n.kind === "repository");
   if (!hasNotes && !hasRepo) return "no notes yet — add one with the weave_note tool";
   return null;

package/src/opencode/commands.ts

@@ -1,5 +1,5 @@
-import { hashContent } from "../core";
-import type { SessionDigest } from "../core";
+import { hashContent, type SessionDigest } from "../core";
+import { digestFromMessages } from "../core/sessionDigest";
 import { createWorkspaceCommands, type WorkspaceScanStatus } from "../core/workspaceCommands";
 import type { WorkspaceServerController } from "../web/server/controller";
 
@@ -15,86 +15,19 @@ function timestamp(value: unknown): string {
   return typeof value === "number" && Number.isFinite(value) ? new Date(value).toISOString() : "";
 }
 
-function clipped(value: unknown, max: number): string {
-  if (typeof value !== "string") return "";
-  const text = value.trim();
-  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
-}
-
 /** Convert OpenCode's public session context to the portable session digest. */
 export function openCodeSessionDigest(session: unknown, messages: readonly unknown[]): SessionDigest {
   const info = record(session);
   const time = record(info.time);
   const location = record(info.location);
-  const relevant = messages.filter((message) => ["user", "assistant", "compaction", "shell"].includes(String(record(message).type)));
-  const digest: SessionDigest = {
+  return digestFromMessages({
     id: String(info.id ?? ""),
     cwd: typeof location.directory === "string" ? location.directory : "",
     parentSession: typeof info.parentID === "string" ? info.parentID : null,
     startedAt: timestamp(time.created),
     endedAt: timestamp(time.updated),
     name: typeof info.title === "string" && info.title.trim() ? info.title.trim() : null,
-    models: [],
-    userCount: 0,
-    assistantCount: 0,
-    toolResultCount: 0,
-    errors: 0,
-    bashCount: 0,
-    tools: {},
-    firstUserMessage: null,
-    userMessages: [],
-    compactions: [],
-    branchSummaries: [],
-    lastAssistantText: null,
-  };
-  for (const raw of relevant) {
-    const message = record(raw);
-    if (message.type === "user") {
-      digest.userCount += 1;
-      const text = clipped(message.text, 400);
-      if (text) {
-        digest.userMessages.push(text);
-        if (digest.userMessages.length > 60) digest.userMessages.shift();
-        digest.firstUserMessage ??= clipped(text, 120);
-      }
-      continue;
-    }
-    if (message.type === "shell") {
-      digest.bashCount += 1;
-      continue;
-    }
-    if (message.type === "compaction") {
-      const summary = clipped(message.summary, 1_200);
-      if (summary) {
-        digest.compactions.push(summary);
-        if (digest.compactions.length > 3) digest.compactions.shift();
-      }
-      continue;
-    }
-    digest.assistantCount += 1;
-    const model = record(message.model);
-    if (typeof model.providerID === "string" && typeof model.id === "string") {
-      const label = `${model.providerID}/${model.id}`;
-      if (!digest.models.includes(label)) digest.models.push(label);
-    }
-    if (message.finish === "error" || message.error) digest.errors += 1;
-    const content = Array.isArray(message.content) ? message.content : [];
-    const text = content
-      .filter((part) => record(part).type === "text")
-      .map((part) => record(part).text)
-      .filter((part): part is string => typeof part === "string")
-      .join("\n");
-    if (text.trim()) digest.lastAssistantText = clipped(text, 1_200);
-    for (const part of content) {
-      const tool = record(part);
-      if (tool.type !== "tool") continue;
-      digest.toolResultCount += 1;
-      const name = typeof tool.name === "string" ? tool.name : "unknown";
-      digest.tools[name] = (digest.tools[name] ?? 0) + 1;
-      if (record(tool.state).status === "error") digest.errors += 1;
-    }
-  }
-  return digest;
+  }, messages);
 }
 
 export async function registerOpenCodeCommands(

package/src/opencode/index.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { formatStatusLine, getWorkspaceStatus } from "../core";
 import { parseFrontMatter, unquoteField } from "../core/frontmatter";
 import { registerOpenCodeCommands } from "./commands";
-import { weaveTools } from "./tools";
+import { weaveTools } from "../core/tools";
 import { WEAVE_RPC } from "./rpc";
 import { WorkspaceServerController } from "../web/server/controller";
 

package/src/opencode/v1.ts

@@ -6,7 +6,7 @@ import { hashContent } from "../core";
 import { createWorkspaceCommands } from "../core/workspaceCommands";
 import { WorkspaceServerController } from "../web/server/controller";
 import { openCodeSessionDigest } from "./commands";
-import { weaveTools } from "./tools";
+import { weaveTools } from "../core/tools";
 
 type Client = Parameters<Plugin>[0]["client"];
 type CommandResult = { lines: string[]; viewer?: { url: string; open: boolean } };

package/src/pi/tools/noteTool.ts

@@ -1,18 +1,16 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import {
-  executeNoteAction,
-  formatRawAppend,
-  WEAVE_NOTE_DESCRIPTION,
-} from "../../core";
+import { formatRawAppend } from "../../core";
+import { weaveTools } from "../../core/tools";
+import { piParameters } from "./parameters";
+
+const tool = weaveTools.find((definition) => definition.name === "weave_note")!;
 
 /** `weave_note` — the smart-notepad tool (design §1: vault knowledge). */
 export function registerNoteTool(pi: ExtensionAPI): void {
   pi.registerTool({
-    name: "weave_note",
+    name: tool.name,
     label: "Weave Note",
-    description: WEAVE_NOTE_DESCRIPTION,
+    description: tool.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.",
@@ -20,20 +18,10 @@ export function registerNoteTool(pi: ExtensionAPI): void {
       "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.",
     ],
-    parameters: Type.Object({
-      action: StringEnum(["list", "get", "add", "append", "finalize", "search", "links", "suggest"] as const),
-      title: Type.Optional(Type.String({ description: "Note title (add)" })),
-      text: Type.Optional(Type.String({ description: "Markdown body (add), addition (append), or restructured body above the raw tail (finalize)" })),
-      tags: Type.Optional(Type.Array(Type.String(), { description: "Tags (add)" })),
-      slug: Type.Optional(Type.String({ description: "Note slug (get, append, finalize)" })),
-      raw: Type.Optional(Type.Boolean({ description: "add/append: keep text as verbatim dictation in the ## Raw tail (timestamped fenced block; tail created if missing). Use for the user's own words, including the first words of a dictated note; omit for structured Markdown" })),
-      source: Type.Optional(StringEnum(["human", "agent"] as const, { description: "Provenance (add): human for user-scribbled notes, agent for Pi-drafted (default agent)" })),
-      query: Type.Optional(Type.String({ description: "Search query (search)" })),
-      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)" })),
-    }),
+    parameters: piParameters(tool.input),
     async execute(_toolCallId, params) {
-      const result = await executeNoteAction(params);
+      // The vault is global, so weave_note ignores the working directory.
+      const result = await tool.execute(params, "");
       return { content: [{ type: "text", text: result.text }], details: result.details };
     },
   });

package/src/pi/tools/parameters.ts

@@ -0,0 +1,10 @@
+import type { TSchema } from "typebox";
+
+/**
+ * Pi accepts plain JSON Schema for tool parameters: its validator coerces and
+ * checks schemas that carry no TypeBox kind. The shared definitions in
+ * `src/core/tools.ts` are plain JSON Schema, so they only need the type.
+ */
+export function piParameters(schema: object): TSchema {
+  return structuredClone(schema) as TSchema;
+}

package/src/pi/tools/repoTool.ts

@@ -1,23 +1,22 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { executeRepoAction, WEAVE_REPO_DESCRIPTION } from "../../core";
+import { weaveTools } from "../../core/tools";
+import { piParameters } from "./parameters";
+
+const tool = weaveTools.find((definition) => definition.name === "weave_repo")!;
 
 /** `weave_repo` — the repository-exploration tool (design §2/§8). */
 export function registerRepoTool(pi: ExtensionAPI): void {
   pi.registerTool({
-    name: "weave_repo",
+    name: tool.name,
     label: "Weave Repo",
-    description: WEAVE_REPO_DESCRIPTION,
+    description: tool.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.",
     ],
-    parameters: Type.Object({
-      action: StringEnum(["overview"] as const),
-    }),
+    parameters: piParameters(tool.input),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const result = await executeRepoAction(params, ctx.cwd);
+      const result = await tool.execute(params, ctx.cwd);
       return { content: [{ type: "text", text: result.text }], details: result.details };
     },
   });