pi-weave 0.1.7 → 0.1.9

package/src/pi/index.ts

@@ -11,8 +11,10 @@ import {
 } from "../core";
 import { registerNoteTool } from "./tools/noteTool";
 import { registerRepoTool } from "./tools/repoTool";
+import { formatSessionScanResult, scanPiSessions } from "./sessionScan";
 import { deepScanRepository, formatDeepScanResult } from "./summarize";
 import { runWeaveViewTui } from "./viewer/tui/run";
+import { WebWorkspaceController } from "./viewer/web/run";
 
 /**
  * pi-weave — an agent-native knowledge workspace (docs/design.md):
@@ -27,13 +29,21 @@ export default function piWeave(pi: ExtensionAPI): void {
   registerNoteTool(pi);
   registerRepoTool(pi);
 
-  // /weave-view is the in-terminal explorer (the old browser viewer was
-  // retired for a pixi.js rewrite); it holds no session resources, so there
-  // is no per-session lifecycle to tear down.
+  // /weave-view opens the browser workspace by default (weave-workspace §13);
+  // `tui` selects the in-terminal explorer. The browser workspace owns a
+  // server, a file watcher and live SSE streams for the rest of the session,
+  // so unlike the TUI it has a real teardown — see `session_shutdown` below.
   let lastCtx: ExtensionContext | ExtensionCommandContext | null = null;
   let lastStatusText: string | undefined = undefined;
   let isActive = false;
 
+  const web = new WebWorkspaceController({
+    exec: (command, args) => pi.exec(command, args),
+    // A boot or an idle shutdown changes what the status line should say, and
+    // neither happens inside a command handler that could refresh it itself.
+    onStateChange: () => updateStatus(),
+  });
+
   function updateStatus(ctx?: ExtensionContext | ExtensionCommandContext, text?: string): void {
     if (ctx) lastCtx = ctx;
     const c = ctx || lastCtx;
@@ -41,24 +51,50 @@ export default function piWeave(pi: ExtensionAPI): void {
     if (text !== undefined) {
       lastStatusText = text;
     }
-    if (!lastStatusText) {
+
+    // A running browser workspace is a background process the user cannot
+    // otherwise see — an open port on their machine — so it always gets a
+    // marker. Resolved *before* the "nothing to show" test, because the port
+    // is itself something to show.
+    //
+    // This ordering is the fix for a real bug: the early return used to sit
+    // above this lookup, so a workspace started in a session that never
+    // emitted `session_start` (no seeded `lastStatusText`) did not merely
+    // fail to gain the marker — it actively cleared the status line while a
+    // server was listening. The browser-launch-failure path is exactly that
+    // shape, which is why it was the case that caught it.
+    const port = web.port();
+    const suffix = port === null ? "" : ` · web:${port}`;
+
+    // Clear only when there is genuinely nothing to say: no base text *and*
+    // no server.
+    if (!lastStatusText && port === null) {
       c.ui.setStatus("weave", undefined);
       return;
     }
+
     let theme: { fg?: (slot: string, text: string) => string } | undefined;
     try {
       theme = (c.ui as unknown as { theme?: { fg?: (slot: string, text: string) => string } })?.theme;
     } catch {
       // ignore
     }
-    const indicator = (isActive || inFlightDeepScans.size > 0)
+    const indicator = (isActive || inFlightDeepScans.size > 0 || inFlightSessionScans.size > 0)
       ? (theme?.fg ? theme.fg("accent", "●") : "●")
       : (theme?.fg ? theme.fg("dim", "○") : "○");
-    c.ui.setStatus("weave", `${indicator} ${lastStatusText}`);
+    // With no base text the marker stands alone (`○ web:51234`) rather than
+    // rendering a leading ` · ` separator against nothing.
+    const body = lastStatusText ? `${lastStatusText}${suffix}` : `web:${port}`;
+    c.ui.setStatus("weave", `${indicator} ${body}`);
   }
 
   pi.on("session_shutdown", async () => {
-    // The TUI explorer owns no session-scoped resources; nothing to stop.
+    // The TUI explorer owns nothing session-scoped, but the browser workspace
+    // owns an HTTP server, a recursive file watcher and any number of open SSE
+    // streams. `close()` releases all three (server.ts closes the hub and
+    // awaits the watcher); a leaked listener outliving the pi session is a
+    // real bug, not a tidiness concern.
+    await web.close();
   });
 
   pi.on("agent_start", async (_event, ctx) => {
@@ -97,20 +133,45 @@ export default function piWeave(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("weave-view", {
-    description: "Open the in-terminal knowledge-graph explorer (vault + repository); reads from disk live",
+    description: "Open the knowledge workspace in your browser ('tui' for the in-terminal explorer, '--no-open' to just print the URL)",
     handler: async (args, ctx) => {
-      const arg = args.trim().toLowerCase();
-      if (arg !== "" && arg !== "tui") {
-        ctx.ui.notify("usage: /weave-view [tui]", "warning");
+      const parsed = parseWeaveViewArgs(args);
+      if (parsed === null) {
+        ctx.ui.notify(WEAVE_VIEW_USAGE, "warning");
         return;
       }
-      await runWeaveViewTui(ctx);
+      if (parsed.surface === "tui") {
+        await runWeaveViewTui(ctx);
+        return;
+      }
+      const outcome = await web.run(ctx, { open: parsed.open });
+      // A browser that would not launch on a machine that has a terminal
+      // still leaves the user somewhere to go. The server stays up — the URL
+      // in the notification remains valid — and the TUI opens on top of it.
+      if (outcome.fallbackToTui && ctx.mode === "tui") await runWeaveViewTui(ctx);
+      // Unconditionally, and last: the TUI writes its own status line on
+      // close, which would otherwise drop the `· web:PORT` marker for a
+      // server that is still running.
+      updateStatus(ctx);
     },
   });
 
   pi.registerCommand("weave-scan", {
-    description: "Build or refresh the repository knowledge index (.okf); 'deep' also summarizes files with the session model",
+    description:
+      "Build or refresh the repository knowledge index (.okf); 'deep' also summarizes files with the session model; 'sessions' summarizes pi session history into the vault",
     handler: async (args, ctx) => {
+      const mode = args.trim().toLowerCase();
+      if (mode === "sessions") {
+        // Repo-agnostic by definition: no git requirement, works from any cwd.
+        if (inFlightSessionScans.size > 0) {
+          ctx.ui.notify("pi-weave: a session scan is already running — run /weave-scan-cancel to stop it.", "warning");
+          return;
+        }
+        const status = await getWorkspaceStatus(ctx.cwd);
+        startSessionScan(ctx, status, updateStatus);
+        return; // the background scan owns the status line until it settles
+      }
+
       const root = await findGitRoot(ctx.cwd);
       if (!root) {
         ctx.ui.notify("pi-weave: not inside a git repository.", "warning");
@@ -124,7 +185,7 @@ export default function piWeave(pi: ExtensionAPI): void {
       await writeRepoIndex(root, index);
       ctx.ui.notify(`pi-weave: index refreshed\n${summarizeIndex(index).join("\n")}`, "info");
 
-      if (args.trim().toLowerCase() === "deep") {
+      if (mode === "deep") {
         if (inFlightDeepScans.has(root)) {
           ctx.ui.notify("pi-weave: a deep scan is already running for this repository — run /weave-scan-cancel to stop it.", "warning");
         } else {
@@ -142,20 +203,68 @@ export default function piWeave(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("weave-scan-cancel", {
-    description: "Cancel an in-flight /weave-scan deep run",
+    description: "Cancel an in-flight /weave-scan deep or sessions run",
     handler: async (_args, ctx) => {
       const root = await findGitRoot(ctx.cwd);
-      const scan = root ? inFlightDeepScans.get(root) : undefined;
-      if (!scan) {
+      const deep = root ? inFlightDeepScans.get(root) : undefined;
+      const sessions = inFlightSessionScans.get(SESSIONS_SCAN_KEY);
+      if (!deep && !sessions) {
         ctx.ui.notify("pi-weave: no deep scan is currently running.", "info");
         return;
       }
-      scan.controller.abort();
-      ctx.ui.notify("pi-weave: deep scan cancellation requested.", "info");
+      deep?.controller.abort();
+      sessions?.controller.abort();
+      ctx.ui.notify("pi-weave: scan cancellation requested.", "info");
     },
   });
 }
 
+/* ------------------------------------------------------------------ */
+/* /weave-view argument parsing                                        */
+/* ------------------------------------------------------------------ */
+
+export const WEAVE_VIEW_USAGE = "usage: /weave-view [tui|web] [--no-open]";
+
+/** Which explorer `/weave-view` was asked for. */
+export interface WeaveViewArgs {
+  surface: "tui" | "web";
+  /** `false` for `--no-open`. Meaningless for `tui`, which never opens one. */
+  open: boolean;
+}
+
+/**
+ * Parse `/weave-view`'s argument string, or `null` for "print the usage".
+ *
+ * Bare `/weave-view` is the **browser** workspace (weave-workspace §13):
+ * the default is the thing most people want most of the time, and `tui` is
+ * one word away for the SSH case. `--no-open` is accepted on the web
+ * surface only — silently ignoring it after `tui` would be a lie about what
+ * happened.
+ *
+ * Exported because a parser is exactly the kind of thing that should be
+ * tested as a table rather than through eight command invocations.
+ */
+export function parseWeaveViewArgs(args: string): WeaveViewArgs | null {
+  const tokens = args.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  let surface: "tui" | "web" = "web";
+  let open = true;
+  let sawSurface = false;
+  for (const token of tokens) {
+    if (token === "--no-open") {
+      // Rejecting the repeat costs nothing and keeps "did I typo?" honest.
+      if (!open) return null;
+      open = false;
+      continue;
+    }
+    if (sawSurface) return null;
+    if (token !== "tui" && token !== "web") return null;
+    surface = token;
+    sawSurface = true;
+  }
+  if (surface === "tui" && !open) return null;
+  return { surface, open };
+}
+
 /* ------------------------------------------------------------------ */
 /* In-flight deep scans (background, cancellable)                      */
 /* ------------------------------------------------------------------ */
@@ -169,60 +278,151 @@ interface InFlightDeepScan {
 /** In-flight deep scans keyed by repo root — the /weave-scan-cancel target. */
 const inFlightDeepScans = new Map<string, InFlightDeepScan>();
 
+/**
+ * The in-flight session scan, under a reserved key that cannot collide with
+ * a git root (absolute paths always start with `/`).
+ */
+export const SESSIONS_SCAN_KEY = "(pi-weave:sessions)";
+const inFlightSessionScans = new Map<string, InFlightDeepScan>();
+
 /** Test seam: resolve when the in-flight deep scan for `root` settles. */
 export async function deepScanDone(root: string): Promise<void | undefined> {
   const canonical = await findGitRoot(root).catch(() => null);
   return inFlightDeepScans.get(canonical ?? root)?.done;
 }
 
+/** Test seam: resolve when the background session scan settles. */
+export async function sessionScanDone(): Promise<void | undefined> {
+  return inFlightSessionScans.get(SESSIONS_SCAN_KEY)?.done;
+}
+
+interface SettledMessage {
+  text: string;
+  level: "info" | "warning";
+}
+
 /**
- * Kick off a deep scan in the background so the user keeps control of the
- * session (a blocking command can't be cancelled in the TUI — Esc only aborts
- * streaming/bash). Progress is pushed to the status line; completion or
- * cancellation is reported via a notification. `baseStatus` is the workspace
- * status captured before the scan and restored when it settles.
+ * Shared background-scan lifecycle for the LLM-backed modes: the scan runs
+ * off the command handler so the user keeps control of the session (a
+ * blocking command can't be cancelled in the TUI — Esc only aborts
+ * streaming/bash). Progress is pushed to the status line; the completion
+ * message is notified; the settled status is restored when the scan settles
+ * (`settledStatus` lets a scan recompute it — a session scan grows the vault,
+ * so its restored line should say so).
  */
-function startDeepScan(
-  root: string,
+function startBackgroundScan(
+  store: Map<string, InFlightDeepScan>,
+  key: string,
   ctx: ExtensionCommandContext,
   baseStatus: WorkspaceStatus,
   updateStatus: (ctx?: ExtensionContext | ExtensionCommandContext, text?: string) => void,
+  run: (signal: AbortSignal) => Promise<SettledMessage | null>,
+  settledStatus: (() => Promise<WorkspaceStatus>) | undefined = undefined,
 ): void {
   const controller = new AbortController();
   let doneResolve: () => void;
   const done = new Promise<void>((resolve) => {
     doneResolve = resolve;
   });
-  inFlightDeepScans.set(root, { controller, done });
+  store.set(key, { controller, done });
 
   void (async () => {
     try {
-      updateStatus(ctx, "🧵 deep scan: starting…");
-      const outcome = await deepScanRepository(root, ctx, {
-        onProgress: ({ current, total, path }) => {
-          const pct = total > 0 ? Math.round((current / total) * 100) : 100;
-          updateStatus(ctx, `🧵 deep scan: ${current}/${total} (${pct}%) — ${path}`);
-        },
-        signal: controller.signal,
-      });
-      if (controller.signal.aborted) {
-        ctx.ui.notify("pi-weave: deep scan cancelled.", "warning");
-      } else if (outcome.kind === "no-model") {
-        ctx.ui.notify(
-          "pi-weave: deep scan needs an active session model — none configured. Light index only.",
-          "warning",
-        );
-      } else if (outcome.kind === "ok") {
-        ctx.ui.notify(`pi-weave: deep scan complete — ${formatDeepScanResult(outcome.result)}`, "info");
-      }
+      const settled = await run(controller.signal);
+      if (settled !== null) ctx.ui.notify(settled.text, settled.level);
     } catch {
       // session ended or extension torn down — stop quietly
     } finally {
       // Restore the settled status before removing the map entry, so a caller
-      // awaiting deepScanDone() observes the settled status line.
-      inFlightDeepScans.delete(root);
-      updateStatus(ctx, formatStatusLine(baseStatus));
+      // awaiting the done seam observes the settled status line.
+      const final = settledStatus
+        ? await settledStatus().catch(() => baseStatus)
+        : baseStatus;
+      store.delete(key);
+      updateStatus(ctx, formatStatusLine(final));
       doneResolve!();
     }
   })();
 }
+
+/**
+ * Kick off a deep scan in the background. `baseStatus` is the workspace
+ * status captured before the scan and restored when it settles.
+ */
+function startDeepScan(
+  root: string,
+  ctx: ExtensionCommandContext,
+  baseStatus: WorkspaceStatus,
+  updateStatus: (ctx?: ExtensionContext | ExtensionCommandContext, text?: string) => void,
+): void {
+  startBackgroundScan(inFlightDeepScans, root, ctx, baseStatus, updateStatus, async (signal) => {
+    updateStatus(ctx, "🕸️ deep scan: starting…");
+    const outcome = await deepScanRepository(root, ctx, {
+      onProgress: ({ current, total, path }) => {
+        const pct = total > 0 ? Math.round((current / total) * 100) : 100;
+        updateStatus(ctx, `🕸️ deep scan: ${current}/${total} (${pct}%) — ${path}`);
+      },
+      signal,
+    });
+    if (signal.aborted) {
+      return { text: "pi-weave: deep scan cancelled.", level: "warning" };
+    }
+    if (outcome.kind === "no-model") {
+      return {
+        text: "pi-weave: deep scan needs an active session model — none configured. Light index only.",
+        level: "warning",
+      };
+    }
+    if (outcome.kind === "ok") {
+      return { text: `pi-weave: deep scan complete — ${formatDeepScanResult(outcome.result)}`, level: "info" };
+    }
+    return null;
+  });
+}
+
+/**
+ * Kick off a session scan (docs/session-scan.md) in the background — same
+ * lifecycle as deep scans; keyed globally, not per repo.
+ */
+function startSessionScan(
+  ctx: ExtensionCommandContext,
+  baseStatus: WorkspaceStatus,
+  updateStatus: (ctx?: ExtensionContext | ExtensionCommandContext, text?: string) => void,
+): void {
+  startBackgroundScan(
+    inFlightSessionScans,
+    SESSIONS_SCAN_KEY,
+    ctx,
+    baseStatus,
+    updateStatus,
+    async (signal) => {
+      updateStatus(ctx, "🕸️ session scan: starting…");
+      const outcome = await scanPiSessions(ctx, {
+        onProgress: ({ current, total, path }) => {
+          const pct = total > 0 ? Math.round((current / total) * 100) : 100;
+          updateStatus(ctx, `🕸️ session scan: ${current}/${total} (${pct}%) — ${path}`);
+        },
+        signal,
+      });
+      if (signal.aborted) {
+        return { text: "pi-weave: session scan cancelled.", level: "warning" };
+      }
+      if (outcome.kind === "no-model") {
+        return {
+          text: "pi-weave: session scan needs an active session model — none configured.",
+          level: "warning",
+        };
+      }
+      const result = outcome.result;
+      if (result.discovered === 0) {
+        return { text: "pi-weave: session scan complete — no pi sessions found.", level: "info" };
+      }
+      return { text: `pi-weave: session scan complete — ${formatSessionScanResult(result)}`, level: "info" };
+    },
+    // Unlike the deep scan (whose settled status is precomputed to avoid git
+    // contention), the session scan writes vault notes and takes no git lock:
+    // recompute the workspace status so the settled line counts the notes it
+    // just wrote.
+    () => getWorkspaceStatus(ctx.cwd),
+  );
+}

package/src/pi/sessionScan.ts

@@ -0,0 +1,104 @@
+/**
+ * pi adapter for the session scan (docs/session-scan.md): summarize pi
+ * session transcripts into the vault as incremental memory notes.
+ *
+ * Model wiring is shared with the deep scan (`createModelSummarizer` — the
+ * session's already-configured model, auth via `modelRegistry`); only the
+ * prompt differs, because a session transcript wants different sentences
+ * than a source file. `deps.complete` is the test seam — no network in unit
+ * tests.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  resolveSessionsRoot,
+  resolveVaultRoot,
+  runSessionScan,
+  type SessionScanOptions,
+  type SessionScanResult,
+  type SummarizeFn,
+} from "../core";
+import { createModelSummarizer, type SummarizerDeps } from "./summarize";
+
+const SESSION_SYSTEM_PROMPT = [
+  "You write durable memory notes that compact coding-agent sessions into their bottom line.",
+  "Answer, in order: what happened, what we did, what shipped (features, files, commands,",
+  "decisions), and what went less well (dead ends, breakage, anything left unfinished).",
+  "Technical sessions get specifics — real file paths, commands, outcomes — not generalities.",
+  "3–6 sentences, past tense. No preamble, no headings, no code fences.",
+].join("\n");
+
+const SESSION_MAX_OUTPUT_TOKENS = 400;
+
+/** Session summarizer over the session model, or null when none is active. */
+export function createSessionSummarizer(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  deps: SummarizerDeps = {},
+): { summarize: SummarizeFn; label: string } | null {
+  return createModelSummarizer(ctx, SESSION_SYSTEM_PROMPT, SESSION_MAX_OUTPUT_TOKENS, deps);
+}
+
+export type SessionScanOutcome =
+  | { kind: "ok"; result: SessionScanResult }
+  | { kind: "no-model" };
+
+export interface SessionScanAdapterOptions {
+  complete?: SummarizerDeps["complete"];
+  maxSessions?: SessionScanOptions["maxSessions"];
+  maxFileBytes?: SessionScanOptions["maxFileBytes"];
+  concurrency?: SessionScanOptions["concurrency"];
+  sessionsRoot?: SessionScanOptions["sessionsRoot"];
+  vaultRoot?: SessionScanOptions["vaultRoot"];
+  now?: SessionScanOptions["now"];
+  onProgress?: SessionScanOptions["onProgress"];
+  signal?: SessionScanOptions["signal"];
+}
+
+/**
+ * Scan pi sessions into the vault using the session model. Roots default to
+ * the real locations (PI_WEAVE_SESSIONS / PI_WEAVE_VAULT overrides apply);
+ * tests inject both.
+ */
+export async function scanPiSessions(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  deps: SessionScanAdapterOptions = {},
+): Promise<SessionScanOutcome> {
+  const llm = createSessionSummarizer(
+    ctx,
+    deps.complete !== undefined ? { complete: deps.complete } : {},
+  );
+  if (!llm) return { kind: "no-model" };
+  // exactOptionalPropertyTypes: only present keys may be spread in.
+  const result = await runSessionScan({
+    sessionsRoot: deps.sessionsRoot ?? resolveSessionsRoot(),
+    vaultRoot: deps.vaultRoot ?? resolveVaultRoot(),
+    summarize: llm.summarize,
+    model: llm.label,
+    ...(deps.maxSessions !== undefined ? { maxSessions: deps.maxSessions } : {}),
+    ...(deps.maxFileBytes !== undefined ? { maxFileBytes: deps.maxFileBytes } : {}),
+    ...(deps.concurrency !== undefined ? { concurrency: deps.concurrency } : {}),
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+    ...(deps.onProgress !== undefined ? { onProgress: deps.onProgress } : {}),
+    ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+  });
+  return { kind: "ok", result };
+}
+
+/** One-line human summary of a session-scan result (for notify output). */
+export function formatSessionScanResult(result: SessionScanResult): string {
+  const parts = [
+    `${result.written} summarized (${result.created} new, ${result.updated} updated)`,
+    `${result.skippedFresh} unchanged`,
+  ];
+  if (result.skippedEmpty > 0) parts.push(`${result.skippedEmpty} empty`);
+  if (result.skippedTooBig > 0) parts.push(`${result.skippedTooBig} skipped (size)`);
+  if (result.skippedUnreadable > 0) parts.push(`${result.skippedUnreadable} unreadable`);
+  let text = `${parts.join(", ")} — ${result.considered} sessions considered`;
+  if (result.failed.length > 0) {
+    const [failed0] = result.failed;
+    if (failed0) {
+      text += `; ${result.failed.length} failed, first: ${failed0.path}: ${failed0.error}`;
+    }
+  }
+  return text;
+}

package/src/pi/summarize.ts

@@ -44,9 +44,21 @@ const SYSTEM_PROMPT = [
 const MAX_OUTPUT_TOKENS = 220;
 const REQUEST_TIMEOUT_MS = 30_000;
 
-/** Create the model-backed summarizer, or null when the session has no active model. */
-export function createLlmSummarizer(
+/**
+ * The shared session-model wiring behind every pi-weave summarizer (deep
+ * scan, session scan): resolve the session's already-configured model — no
+ * extra keys or providers (docs/scan-modes.md) — drive completion through
+ * `ctx.modelRegistry`, which owns auth, and reject empty outputs so a
+ * degraded model cannot silently blank a note.
+ *
+ * Returns null when the session has no active model (headless runs without a
+ * provider, etc.) — callers fall back or notify. `deps.complete` is the test
+ * seam: unit tests inject a fake and never touch a network.
+ */
+export function createModelSummarizer(
   ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  systemPrompt: string,
+  maxOutputTokens: number,
   deps: SummarizerDeps = {},
 ): LlmSummarizer | null {
   const model = ctx.model;
@@ -58,7 +70,7 @@ export function createLlmSummarizer(
     const message = await complete(
       model,
       {
-        systemPrompt: SYSTEM_PROMPT,
+        systemPrompt,
         messages: [
           {
             role: "user",
@@ -67,7 +79,7 @@ export function createLlmSummarizer(
           },
         ],
       },
-      { maxTokens: MAX_OUTPUT_TOKENS, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) },
+      { maxTokens: maxOutputTokens, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) },
     );
     const text = contentText(message.content).trim();
     if (text.length === 0) {
@@ -78,6 +90,14 @@ export function createLlmSummarizer(
   return { summarize, label };
 }
 
+/** Create the file summarizer for deep scans, or null when no model is active. */
+export function createLlmSummarizer(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  deps: SummarizerDeps = {},
+): LlmSummarizer | null {
+  return createModelSummarizer(ctx, SYSTEM_PROMPT, MAX_OUTPUT_TOKENS, deps);
+}
+
 export type DeepScanOutcome =
   | { kind: "ok"; result: DeepScanResult }
   | { kind: "no-model" }

package/src/pi/tools/noteTool.ts

@@ -5,6 +5,7 @@ import { Type } from "typebox";
 import {
   addNote,
   appendToNote,
+  extractRawTail,
   finalizeNote,
   formatNote,
   formatRawAppend,
@@ -30,7 +31,8 @@ export function registerNoteTool(pi: ExtensionAPI): void {
     description:
       "Read and write notes in the pi-weave vault — a persistent, human-readable knowledge base " +
       "of Markdown notes. Actions: list (all notes), get (one note by slug), add (new note), " +
-      "append (extend a note), finalize (restructure a note above its raw tail), search (title/tags/body). " +
+      "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). " +
       "Use it to remember decisions, facts, and user preferences across sessions.",
     promptSnippet: "Remember and retrieve durable knowledge in the pi-weave vault",
     promptGuidelines: [
@@ -43,6 +45,7 @@ export function registerNoteTool(pi: ExtensionAPI): void {
       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: "append: add text as verbatim dictation to the ## Raw tail (timestamped fenced block; tail created if missing). Use for dictation/scribbles; omit for structured Markdown additions" })),
       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)" })),
     }),
@@ -117,12 +120,14 @@ export function registerNoteTool(pi: ExtensionAPI): void {
           // 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));
+          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: `Appended to ${note.slug} (updated ${note.updated}).` }],
+            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 },
           };
         }
@@ -150,8 +155,12 @@ export function registerNoteTool(pi: ExtensionAPI): void {
           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}). Raw notes tail preserved.` }],
+            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 },
           };
         }