pi-weave 0.1.20 → 0.1.21

package/src/core/vault.ts

@@ -1,11 +1,14 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { promises as fs } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import {
+  MANAGED_FRONT_MATTER_KEYS,
   parseFrontMatter,
   parseNoteFile,
+  quoteField,
   serializeNote,
   unquoteField,
+  upsertFrontMatterFields,
 } from "./frontmatter";
 import { withMutationQueue } from "./mutex";
 import { NOTES_DIR, OKF_MANIFEST } from "./paths";
@@ -349,6 +352,95 @@ export async function finalizeNote(
   });
 }
 
+export interface UpsertNoteInput {
+  slug: string;
+  title: string;
+  body: string;
+  tags?: string[];
+  source?: NoteSource;
+  fields?: Record<string, string>;
+  identity?: { field: string; value: string };
+  now?: Date;
+}
+
+/** Create or refresh generated knowledge without overwriting a different identity. */
+export async function upsertNote(root: string, input: UpsertNoteInput): Promise<Note> {
+  await ensureVault(root);
+  return withVaultLock(root, async () => {
+    const now = (input.now ?? new Date()).toISOString();
+    const identity = input.identity;
+    let existing = await getNote(root, input.slug);
+    if (existing !== null && identity && frontMatterField(existing.frontMatter, identity.field) !== identity.value) {
+      existing = null;
+    }
+    if (existing === null) {
+      const slug = uniqueSlug(input.slug, (candidate) => {
+        if (!existsSync(notePath(root, candidate))) return false;
+        return !identity || fileFrontMatterField(notePath(root, candidate), identity.field) !== identity.value;
+      });
+      const meta: NoteMeta = {
+        title: input.title,
+        created: now,
+        updated: now,
+        tags: input.tags ?? [],
+        source: input.source ?? "generated",
+      };
+      const fields = safeGeneratedFields(input.fields);
+      const frontMatter = [
+        `title: ${quoteField(meta.title)}`,
+        `created: ${meta.created}`,
+        `updated: ${meta.updated}`,
+        `tags: [${meta.tags.map(quoteField).join(", ")}]`,
+        `source: ${meta.source}`,
+        ...upsertFrontMatterFields([], fields),
+      ];
+      return writeNote(notePath(root, slug), slug, meta, input.body, frontMatter);
+    }
+    const fields = safeGeneratedFields(input.fields);
+    const frontMatter = upsertFrontMatterFields(existing.frontMatter ?? [], fields);
+    // The existing tail is re-attached whenever there is one. `input.body` is
+    // generated content (a model summary), so probing it for a `## Raw` marker
+    // would let a summary that merely mentions the heading delete the human's
+    // verbatim tail.
+    const tail = extractRawTail(existing.body);
+    const body = tail === "" ? input.body.trim() : `${input.body.trim()}\n\n${tail}`;
+    return writeNote(
+      notePath(root, input.slug),
+      input.slug,
+      { ...existing, updated: now },
+      body,
+      frontMatter,
+    );
+  });
+}
+
+/**
+ * Identity values are compared **unquoted**, matching how the session note
+ * index reads them: `quoteField` wraps any value containing `:` (an ISO
+ * timestamp used as an id, say), and comparing a quoted value against a raw
+ * one never matches — which would fork a new `-2`, `-3`… note on every scan.
+ */
+function frontMatterField(lines: NoteFrontMatter | undefined, field: string): string | null {
+  if (!lines) return null;
+  const value = parseFrontMatter(["---", ...lines, "---", ""].join("\n"))?.fields.get(field);
+  return value === undefined ? null : unquoteField(value);
+}
+
+function fileFrontMatterField(path: string, field: string): string | null {
+  try {
+    const value = parseFrontMatter(readFileSync(path, "utf8"))?.fields.get(field);
+    return value === undefined ? null : unquoteField(value);
+  } catch {
+    return null;
+  }
+}
+
+function safeGeneratedFields(fields: Record<string, string> | undefined): Record<string, string> {
+  if (!fields) return {};
+  const managed = new Set<string>(MANAGED_FRONT_MATTER_KEYS);
+  return Object.fromEntries(Object.entries(fields).filter(([key]) => !managed.has(key) && /^[A-Za-z][A-Za-z0-9_-]*$/.test(key)));
+}
+
 export type VaultMutationResult =
   | { ok: true; slug?: string; path?: string }
   | { ok: false; reason: "missing" | "collision" | "invalid" };

package/src/pi/index.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import {
   buildRepoIndex,
   findGitRoot,
@@ -11,6 +13,7 @@ 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";
@@ -78,7 +81,7 @@ export default function piWeave(pi: ExtensionAPI): void {
     } 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", "○") : "○");
     // With no base text the marker stands alone (`○ web:51234`) rather than
@@ -157,9 +160,22 @@ export default function piWeave(pi: ExtensionAPI): void {
 
   pi.registerCommand("weave-scan", {
     description:
-      "Build or refresh the repository knowledge index (.okf); 'deep' also summarizes files with the session model",
+      "Build or refresh the repository index; 'deep' summarizes files; 'sessions [dir]' summarizes session history",
     handler: async (args, ctx) => {
-      const mode = args.trim().toLowerCase();
+      const input = args.trim();
+      const [mode = "", ...rest] = input.split(/\s+/);
+      if (mode.toLowerCase() === "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);
+        const path = rest.length > 0 ? resolveHistoryPath(ctx.cwd, rest.join(" ")) : undefined;
+        startSessionScan(ctx, status, updateStatus, path);
+        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");
@@ -173,7 +189,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 (mode === "deep") {
+      if (mode.toLowerCase() === "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 {
@@ -191,15 +207,17 @@ 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 deep = root ? inFlightDeepScans.get(root) : undefined;
-      if (!deep) {
-        ctx.ui.notify("pi-weave: no deep scan is currently running.", "info");
+      const sessions = inFlightSessionScans.get(SESSIONS_SCAN_KEY);
+      if (!deep && !sessions) {
+        ctx.ui.notify("pi-weave: no scan is currently running.", "info");
         return;
       }
       deep?.controller.abort();
+      sessions?.controller.abort();
       ctx.ui.notify("pi-weave: scan cancellation requested.", "info");
     },
   });
@@ -209,6 +227,20 @@ export default function piWeave(pi: ExtensionAPI): void {
 /* /weave-view argument parsing                                        */
 /* ------------------------------------------------------------------ */
 
+/**
+ * Resolve the optional `/weave-scan sessions <path>` argument.
+ *
+ * Command arguments reach the handler unexpanded, and the whole point of this
+ * argument is another harness's history under `$HOME` — so `~/` is the form
+ * users type, and leaving it literal silently scans nothing.
+ */
+export function resolveHistoryPath(cwd: string, input: string): string {
+  const trimmed = input.trim();
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith("~/")) return join(homedir(), trimmed.slice(2));
+  return resolve(cwd, trimmed);
+}
+
 export const WEAVE_VIEW_USAGE = "usage: /weave-view [tui|web] [--no-open]";
 
 /** Which explorer `/weave-view` was asked for. */
@@ -264,12 +296,24 @@ 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";
@@ -280,7 +324,9 @@ interface SettledMessage {
  * 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.
+ * 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 startBackgroundScan(
   store: Map<string, InFlightDeepScan>,
@@ -289,6 +335,7 @@ function startBackgroundScan(
   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;
@@ -306,8 +353,11 @@ function startBackgroundScan(
     } finally {
       // Restore the settled status before removing the map entry, so a caller
       // awaiting the done seam observes the settled status line.
+      const final = settledStatus
+        ? await settledStatus().catch(() => baseStatus)
+        : baseStatus;
       store.delete(key);
-      updateStatus(ctx, formatStatusLine(baseStatus));
+      updateStatus(ctx, formatStatusLine(final));
       doneResolve!();
     }
   })();
@@ -347,3 +397,52 @@ function startDeepScan(
     return null;
   });
 }
+
+/**
+ * Kick off a session scan 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,
+  sessionsRoot?: string,
+): void {
+  startBackgroundScan(
+    inFlightSessionScans,
+    SESSIONS_SCAN_KEY,
+    ctx,
+    baseStatus,
+    updateStatus,
+    async (signal) => {
+      updateStatus(ctx, "🕸️ session scan: starting…");
+      const outcome = await scanPiSessions(ctx, {
+        ...(sessionsRoot !== undefined ? { sessionsRoot } : {}),
+        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,105 @@
+/**
+ * pi adapter for the session scan: summarize agent
+ * 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.",
+  "First summarize what happened, what shipped (features, files, commands, decisions), and",
+  "what went less well (dead ends, breakage, unfinished work) using concrete technical details.",
+  "Then add a '## Takeaways' section with 2–4 reusable lessons: gotchas, root causes of tricky",
+  "failures, non-obvious syntax rules, or architecture patterns a future agent can apply.",
+  "Past tense. No preamble or code fences. Omit lessons unsupported by the transcript.",
+].join("\n");
+
+const SESSION_MAX_OUTPUT_TOKENS = 3_000;
+
+/** 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

@@ -45,7 +45,7 @@ const MAX_OUTPUT_TOKENS = 220;
 const REQUEST_TIMEOUT_MS = 30_000;
 
 /**
- * The shared model wiring behind the deep scan: resolve the session's
+ * Shared model wiring for deep and session scans: 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
@@ -62,7 +62,7 @@ export function createModelSummarizer(
   deps: SummarizerDeps = {},
 ): LlmSummarizer | null {
   const model = ctx.model;
-  if (!model) return null;
+  if (!model || !isUsableModel(model)) return null;
   const complete: CompleteFn =
     deps.complete ?? ((m, c, o) => ctx.modelRegistry.complete(m, c, o));
   const label = `${model.provider}/${model.id}`;
@@ -82,14 +82,57 @@ export function createModelSummarizer(
       { maxTokens: maxOutputTokens, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) },
     );
     const text = contentText(message.content).trim();
-    if (text.length === 0) {
-      throw new Error("model returned an empty summary");
-    }
+    if (text.length === 0) throw new Error(emptySummaryReason(message, maxOutputTokens));
     return text;
   };
   return { summarize, label };
 }
 
+/**
+ * True when `ctx.model` is a real model rather than pi's placeholder.
+ *
+ * A session with no resolved model does not hand back `undefined` — it hands
+ * back pi's `DEFAULT_MODEL`, whose provider and id are the literal string
+ * `"unknown"`. That object is truthy, so a `!model` guard passes it straight
+ * through to `modelRegistry.complete`, which throws `Unknown provider:
+ * unknown` once per file. Treating it as "no model" makes the caller report
+ * the actionable "needs an active session model" instead, before spending a
+ * single call.
+ */
+function isUsableModel(model: { provider?: string; id?: string }): boolean {
+  return model.provider !== undefined && model.provider !== "unknown";
+}
+
+/**
+ * Explain an empty completion using what the response actually carries.
+ *
+ * "model returned an empty summary" is true of every failure mode here and
+ * diagnostic of none: an auth error, a reasoning model that spent its whole
+ * budget thinking, and a refusal all produce zero text blocks. Reporting that
+ * bare string once is unhelpful; reporting it 85 times, once per session, is
+ * an outage with no evidence attached. The provider already distinguishes
+ * these through `stopReason`, `errorMessage` and the reasoning-token count,
+ * so the message says which one happened and what to do about it.
+ */
+export function emptySummaryReason(message: AssistantMessage, maxOutputTokens: number): string {
+  const detail = message.errorMessage?.trim();
+  if (message.stopReason === "error") {
+    return `model call failed${detail ? `: ${detail}` : " with no error detail"}`;
+  }
+  // Reasoning tokens are billed against the same budget as output, so a model
+  // thinking at a high effort level can exhaust it before emitting any text.
+  const reasoning = message.usage?.reasoning ?? 0;
+  if (message.stopReason === "length") {
+    return reasoning > 0
+      ? `model spent its entire ${maxOutputTokens}-token budget on reasoning (${reasoning} tokens) and produced no summary — lower the thinking level or raise the cap`
+      : `model hit the ${maxOutputTokens}-token cap before producing a summary`;
+  }
+  if (reasoning > 0) {
+    return `model returned only reasoning (${reasoning} tokens), no summary text`;
+  }
+  return `model returned an empty summary (stopReason: ${message.stopReason})${detail ? `: ${detail}` : ""}`;
+}
+
 /** Create the file summarizer for deep scans, or null when no model is active. */
 export function createLlmSummarizer(
   ctx: Pick<ExtensionContext, "model" | "modelRegistry">,

package/src/pi/tools/noteTool.ts

@@ -37,7 +37,7 @@ export function registerNoteTool(pi: ExtensionAPI): void {
     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.",
+      "Use weave_note with action=search before answering questions about past decisions, people, or projects; generated notes under sessions/ carry takeaways from earlier sessions.",
     ],
     parameters: Type.Object({
       action: StringEnum(["list", "get", "add", "append", "finalize", "search"] as const),