pi-vcc 0.4.0

package/src/core/search-entries.ts

@@ -0,0 +1,230 @@
+import type { Message } from "@mariozechner/pi-ai";
+import type { RenderedEntry } from "./render-entries";
+import { textOf } from "./content";
+
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command?: string;
+  output?: string;
+}
+function isBashExec(m: Message | BashExecutionMessage): m is BashExecutionMessage {
+  return typeof m === "object" && m !== null && (m as unknown as Record<string, unknown>).role === "bashExecution";
+}
+
+export interface SearchHit extends RenderedEntry {
+  /** Context snippet around the first matched term (only when query provided) */
+  snippet?: string;
+  /** Number of query terms matched (for ranking) */
+  matchCount?: number;
+}
+
+const escapeRegex = (s: string): string =>
+  s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Try to compile as regex; fall back to escaped literal. */
+const safeRegex = (pattern: string): RegExp => {
+  try {
+    return new RegExp(pattern, "i");
+  } catch {
+    return new RegExp(escapeRegex(pattern), "i");
+  }
+};
+
+/** Detect if the query looks like a single regex pattern (contains regex metacharacters). */
+const looksLikeRegex = (query: string): boolean =>
+  /[|*+?{}()[\]\\^$.]/.test(query);
+
+/** Build a regex for snippet highlighting — matches first available term. */
+const snippetRegex = (terms: string[]): RegExp => {
+  const alts = terms.map((t) => {
+    try {
+      // Validate that it's a valid regex
+      new RegExp(t, "i");
+      return t;
+    } catch {
+      return escapeRegex(t);
+    }
+  });
+  return new RegExp(alts.join("|"), "i");
+};
+
+// ── Stopwords for natural language queries ──
+const STOPWORDS = new Set([
+  // English
+  "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "could",
+  "should", "may", "might", "can", "shall", "of", "in", "to", "for",
+  "with", "on", "at", "from", "by", "as", "into", "through", "during",
+  "before", "after", "above", "below", "between", "out", "off", "over",
+  "under", "again", "further", "then", "once", "here", "there", "when",
+  "where", "why", "how", "all", "both", "each", "few", "more", "most",
+  "other", "some", "such", "no", "nor", "not", "only", "own", "same",
+  "so", "than", "too", "very", "just", "about", "it", "its", "that",
+  "this", "what", "which", "who", "whom", "these", "those",
+]);
+
+/** Remove stopwords, keep meaningful terms. */
+const filterStopwords = (terms: string[]): string[] => {
+  const meaningful = terms.filter((t) => !STOPWORDS.has(t.toLowerCase()) && t.length > 1);
+  // If all terms were stopwords, return original (don't lose everything)
+  return meaningful.length > 0 ? meaningful : terms;
+};
+
+/** Count how many distinct terms match the haystack. */
+const countMatches = (hay: string, terms: string[]): number => {
+  let count = 0;
+  for (const t of terms) {
+    if (safeRegex(t).test(hay)) count++;
+  }
+  return count;
+};
+
+// ── BM25-lite scoring ──
+const BM25_K = 1.2;
+const BM25_B = 0.75;
+
+/** Count occurrences of a regex pattern in text. */
+const termFreq = (text: string, pattern: RegExp): number => {
+  const matches = text.match(new RegExp(pattern.source, "gi"));
+  return matches ? matches.length : 0;
+};
+
+interface BM25Context {
+  n: number;         // total docs
+  avgDl: number;     // average doc length (words)
+  df: Map<string, number>; // term -> number of docs containing it
+}
+
+/** Precompute IDF and avgDl across all docs. */
+const buildBM25Context = (docs: string[], terms: string[]): BM25Context => {
+  const n = docs.length;
+  const df = new Map<string, number>();
+  let totalLen = 0;
+
+  for (const doc of docs) {
+    totalLen += doc.split(/\s+/).length;
+    for (const t of terms) {
+      if (safeRegex(t).test(doc)) {
+        df.set(t, (df.get(t) ?? 0) + 1);
+      }
+    }
+  }
+
+  return { n, avgDl: totalLen / Math.max(n, 1), df };
+};
+
+/** BM25 score for a single doc against query terms. */
+const bm25Score = (doc: string, terms: string[], ctx: BM25Context): number => {
+  const dl = doc.split(/\s+/).length;
+  let score = 0;
+
+  for (const t of terms) {
+    const tf = termFreq(doc, safeRegex(t));
+    if (tf === 0) continue;
+
+    const docFreq = ctx.df.get(t) ?? 0;
+    // IDF: log((N - df + 0.5) / (df + 0.5) + 1)
+    const idf = Math.log((ctx.n - docFreq + 0.5) / (docFreq + 0.5) + 1);
+    // TF saturation with length normalization
+    const tfNorm = (tf * (BM25_K + 1)) / (tf + BM25_K * (1 - BM25_B + BM25_B * dl / ctx.avgDl));
+    score += idf * tfNorm;
+  }
+
+  return score;
+};
+
+/** Line-based snippet: ±contextLines around first regex match. */
+const lineSnippet = (text: string, regex: RegExp, contextLines = 2): string | undefined => {
+  const lines = text.split("\n");
+  let matchIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (regex.test(lines[i])) {
+      matchIdx = i;
+      break;
+    }
+  }
+  if (matchIdx === -1) return undefined;
+
+  const start = Math.max(0, matchIdx - contextLines);
+  const end = Math.min(lines.length, matchIdx + contextLines + 1);
+  const slice = lines.slice(start, end);
+
+  const parts: string[] = [];
+  if (start > 0) parts.push(`...(${start} lines above)`);
+  parts.push(...slice);
+  if (end < lines.length) parts.push(`...(${lines.length - end} lines below)`);
+  return parts.join("\n");
+};
+
+/** Build full searchable text for a message. */
+const fullText = (msg: Message | BashExecutionMessage): string => {
+  if (isBashExec(msg)) {
+    return `${msg.command ?? ""} ${msg.output ?? ""}`;
+  }
+  return textOf(msg.content);
+};
+
+export const searchEntries = (
+  entries: RenderedEntry[],
+  messages: Message[],
+  query?: string,
+): SearchHit[] => {
+  if (!query?.trim()) return entries;
+
+  const rawQuery = query.trim();
+
+  // If query looks like a single regex pattern (contains metacharacters),
+  // treat the whole thing as one pattern — don't split into terms
+  if (looksLikeRegex(rawQuery)) {
+    const regex = safeRegex(rawQuery);
+    const hits: SearchHit[] = [];
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      const msg = messages[i];
+      const text = msg ? fullText(msg) : e.summary;
+      const filePart = e.files?.join(" ") ?? "";
+      const hay = `${e.role} ${text} ${filePart}`;
+      if (regex.test(hay)) {
+        const snip = lineSnippet(text, regex);
+        hits.push({ ...e, snippet: snip, matchCount: 1 });
+      }
+    }
+    return hits;
+  }
+
+  // Natural language / multi-word query: BM25 scoring
+  const rawTerms = rawQuery.split(/\s+/);
+  const terms = filterStopwords(rawTerms);
+  const snipRe = snippetRegex(terms);
+
+  // Build all docs for BM25 context
+  const docs: string[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const msg = messages[i];
+    const text = msg ? fullText(msg) : e.summary;
+    const filePart = e.files?.join(" ") ?? "";
+    docs.push(`${e.role} ${text} ${filePart}`);
+  }
+
+  const ctx = buildBM25Context(docs, terms);
+
+  const scored: Array<{ hit: SearchHit; score: number }> = [];
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const hay = docs[i];
+    const mc = countMatches(hay, terms);
+    if (mc === 0) continue;
+    const score = bm25Score(hay, terms, ctx);
+    const text = messages[i] ? fullText(messages[i]) : e.summary;
+    const snip = lineSnippet(text, snipRe);
+    scored.push({
+      hit: { ...e, snippet: snip, matchCount: mc },
+      score,
+    });
+  }
+
+  // Sort by BM25 score desc
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => s.hit);
+};

package/src/core/settings.ts

@@ -0,0 +1,215 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+export const SETTINGS_PATH_DEFAULT = join(homedir(), ".pi", "agent", "pi-vcc-config.json");
+const settingsPath = (): string => process.env.PI_VCC_CONFIG_PATH ?? SETTINGS_PATH_DEFAULT;
+/** Backwards-compat export. Resolves at access time, not import time. */
+export const SETTINGS_PATH = settingsPath();
+
+export interface ExtractionCategoryConfig {
+  /** When false, skip this extraction entirely. Default: true */
+  enabled: boolean;
+}
+
+export interface ReferencesConfig extends ExtractionCategoryConfig {
+  /** Additional URL regex patterns (added to built-in `https?://\\S+`). */
+  extraUrlPatterns: string[];
+  /** Additional GitHub ref patterns (added to built-in `#\\d+`, `PR\\s*#\\d+`, `owner/repo`). */
+  extraGithubRefPatterns: string[];
+  /** Additional version patterns (added to built-in `v?\\d+\\.\\d+\\.\\d+`). */
+  extraVersionPatterns: string[];
+  /** Additional branch patterns (added to built-in `feat|fix|.../xxx`). */
+  extraBranchPatterns: string[];
+}
+
+export interface KeySignalsConfig extends ExtractionCategoryConfig {
+  /** Additional constraint patterns (added to built-in `don't|must not|...`). */
+  extraConstraintPatterns: string[];
+  /** Additional decision patterns (added to built-in `decided|let's use|...`). */
+  extraDecisionPatterns: string[];
+  /** Additional status patterns (added to built-in `DONE|TODO|WIP|...`). */
+  extraStatusPatterns: string[];
+}
+
+export interface GoalsConfig extends ExtractionCategoryConfig {
+  /** Additional task verbs (added to built-in `fix|implement|add|...`). */
+  extraTaskVerbs: string[];
+  /** Additional scope change keywords (added to built-in `instead|actually|...`). */
+  extraScopeChangeWords: string[];
+}
+
+export interface ExtractionConfig {
+  /** References extractor: URLs, GitHub refs, versions, branches. */
+  references: ReferencesConfig;
+  /** Key Signals extractor: constraints, decisions, status markers. */
+  keySignals: KeySignalsConfig;
+  /** Goals extractor tweaks. */
+  goals: GoalsConfig;
+}
+
+export interface PiVccSettings {
+  /**
+   * When true, pi-vcc handles ALL compactions:
+   *   - /compact (no args)
+   *   - /compact <text>
+   *   - auto threshold / overflow
+   *   - /pi-vcc (always handled regardless)
+   *
+   * When false (default), pi-vcc only handles /pi-vcc; everything else
+   * falls back to pi core's default LLM-based compaction.
+   */
+  overrideDefaultCompaction: boolean;
+  /** Write debug snapshot to /tmp/pi-vcc-debug.json on each compaction. */
+  debug: boolean;
+  /** Fine-grained extraction configuration. All patterns are ADDITIVE — built-ins are never removed. */
+  extraction: ExtractionConfig;
+}
+
+const DEFAULT_EXTRACTION: ExtractionConfig = {
+  references: {
+    enabled: true,
+    extraUrlPatterns: [],
+    extraGithubRefPatterns: [],
+    extraVersionPatterns: [],
+    extraBranchPatterns: [],
+  },
+  keySignals: {
+    enabled: true,
+    extraConstraintPatterns: [],
+    extraDecisionPatterns: [],
+    extraStatusPatterns: [],
+  },
+  goals: {
+    enabled: true,
+    extraTaskVerbs: [],
+    extraScopeChangeWords: [],
+  },
+};
+
+export const DEFAULT_SETTINGS: PiVccSettings = {
+  overrideDefaultCompaction: false,
+  debug: false,
+  extraction: DEFAULT_EXTRACTION,
+};
+
+const readJson = async (path: string): Promise<Record<string, unknown> | null> => {
+  try {
+    return JSON.parse(await readFile(path, "utf-8"));
+  } catch (e) {
+    // Intentional fallback: if the file doesn't exist or is invalid JSON, treat as empty.
+    return null;
+  }
+};
+
+function deepMergeExtraction(parsed: Record<string, unknown>): ExtractionConfig {
+  const ext = (parsed.extraction ?? {}) as Record<string, unknown>;
+  const merge = <T extends ExtractionCategoryConfig>(
+    defaults: T,
+    user: Record<string, unknown>,
+  ): T => {
+    const result = { ...defaults };
+    if (typeof user.enabled === "boolean") result.enabled = user.enabled;
+    for (const key of Object.keys(defaults)) {
+      if (key === "enabled") continue;
+      const defVal = defaults[key as keyof T];
+      const userVal = user[key];
+      // Arrays: user value replaces (not merges) to allow full control
+      if (Array.isArray(defVal) && Array.isArray(userVal)) {
+        (result as Record<string, unknown>)[key] = userVal;
+      }
+    }
+    return result;
+  };
+  return {
+    references: merge(DEFAULT_EXTRACTION.references, (ext.references ?? {}) as Record<string, unknown>),
+    keySignals: merge(DEFAULT_EXTRACTION.keySignals, (ext.keySignals ?? {}) as Record<string, unknown>),
+    goals: merge(DEFAULT_EXTRACTION.goals, (ext.goals ?? {}) as Record<string, unknown>),
+  };
+}
+
+export async function loadSettings(): Promise<PiVccSettings> {
+  const parsed = await readJson(settingsPath());
+  if (!parsed || typeof parsed !== "object") return { ...DEFAULT_SETTINGS };
+  const { extraction: _, ...topLevel } = { ...DEFAULT_SETTINGS, ...(parsed as Partial<PiVccSettings>) };
+  const extraction = deepMergeExtraction(parsed);
+  return { ...topLevel, extraction } as PiVccSettings;
+}
+
+/**
+ * Ensure ~/.pi/agent/pi-vcc-config.json exists with default keys.
+ * - File missing → create with full default block.
+ * - File exists but invalid JSON → no-op (don't clobber user file).
+ * - File exists and valid → fill in missing default keys, preserve existing values.
+ */
+/**
+ * @deprecated Use scaffoldSettingsAsync() instead — sync fs blocks the event loop in extension hooks.
+ */
+export function scaffoldSettings(): void {
+  try {
+    const path = settingsPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    if (!existsSync(path)) {
+      writeFileSync(path, `${JSON.stringify(DEFAULT_SETTINGS, null, 2)}\n`);
+      return;
+    }
+
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return; // don't clobber
+
+    let changed = false;
+    const next: Record<string, unknown> = { ...parsed };
+    for (const [key, value] of Object.entries(DEFAULT_SETTINGS)) {
+      if (!(key in next)) {
+        next[key] = value;
+        changed = true;
+      }
+    }
+    if (changed) writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+  } catch (e) {
+    // Intentional fallback: settings scaffolding is best-effort and should not crash the extension load.
+  }
+}
+
+/**
+ * Async version of scaffoldSettings(). Uses fs/promises to avoid blocking the event loop.
+ * - File missing → create with full default block.
+ * - File exists but invalid JSON → no-op (don't clobber user file).
+ * - File exists and valid → fill in missing default keys, preserve existing values.
+ */
+export async function scaffoldSettingsAsync(): Promise<void> {
+  try {
+    const path = settingsPath();
+    const dir = dirname(path);
+
+    let data: string;
+    try {
+      data = await readFile(path, "utf-8");
+    } catch (e: unknown) {
+      if (e instanceof Error && (e as NodeJS.ErrnoException).code === "ENOENT") {
+        // File doesn't exist → create parent dir + default config
+        await mkdir(dir, { recursive: true });
+        await writeFile(path, `${JSON.stringify(DEFAULT_SETTINGS, null, 2)}\n`);
+      }
+      return;
+    }
+
+    const parsed = JSON.parse(data);
+    if (!parsed || typeof parsed !== "object") return; // don't clobber
+
+    let changed = false;
+    const next: Record<string, unknown> = { ...parsed };
+    for (const [key, value] of Object.entries(DEFAULT_SETTINGS)) {
+      if (!(key in next)) {
+        next[key] = value;
+        changed = true;
+      }
+    }
+    if (changed) await writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+  } catch (e) {
+    // Intentional fallback: settings scaffolding is best-effort and should not crash the extension load.
+  }
+}

package/src/core/skill-collapse.ts

@@ -0,0 +1,35 @@
+/** Shared skill-tag collapse utilities */
+
+const SKILL_TAG_RE = /^-?\s*<skill\s+name="([^"]+)"/;
+const SKILL_CLOSE_RE = /^-?\s*<\/skill>/;
+
+/** Collapse skill tags in an array of lines — dedup by name, drop all content inside block */
+export const collapseSkillLines = (lines: string[]): string[] => {
+  const result: string[] = [];
+  const seenSkills = new Set<string>();
+  let insideSkill = false;
+
+  for (const line of lines) {
+    const skillMatch = line.match(SKILL_TAG_RE);
+    if (skillMatch) {
+      insideSkill = true;
+      const name = skillMatch[1];
+      if (!seenSkills.has(name)) {
+        seenSkills.add(name);
+        result.push(`[skill: ${name}]`);
+      }
+      continue;
+    }
+    if (insideSkill) {
+      if (SKILL_CLOSE_RE.test(line)) insideSkill = false;
+      continue;
+    }
+    result.push(line);
+  }
+  return result;
+};
+
+/** Collapse <skill name="X" ...>...</skill> blocks in raw text */
+const SKILL_BLOCK_RE = /<skill\s+name="([^"]+)"[^>]*>[\s\S]*?(?:<\/skill>|$)/g;
+export const collapseSkillText = (text: string): string =>
+  text.replace(SKILL_BLOCK_RE, (_, name) => `[skill: ${name}]`);

package/src/core/summarize.ts

@@ -0,0 +1,159 @@
+import type { Message } from "@mariozechner/pi-ai";
+import type { FileOps } from "../types";
+import { normalize } from "./normalize";
+import { filterNoise } from "./filter-noise";
+import { buildSections } from "./build-sections";
+import { formatSummary, capBrief, RECALL_NOTE } from "./format";
+import { loadSettings, type ExtractionConfig } from "./settings";
+
+export interface CompileInput {
+  messages: Message[];
+  previousSummary?: string;
+  fileOps?: FileOps;
+}
+
+const HEADER_NAMES = ["Session Goal", "Files And Changes", "Commits", "References", "Key Signals", "Outstanding Context", "User Preferences"];
+
+const SEPARATOR = "\n\n---\n\n";
+
+/** Extract a named section from summary text */
+const sectionOf = (text: string, header: string): string => {
+  const tag = `[${header}]`;
+  const start = text.indexOf(tag);
+  if (start < 0) return "";
+  const after = text.slice(start);
+  // Find next section header or separator
+  const nextSection = HEADER_NAMES
+    .filter((h) => h !== header)
+    .map((h) => after.indexOf(`[${h}]`))
+    .filter((n) => n > 0);
+  const nextSep = after.indexOf("\n\n---\n\n");
+  const candidates = [...nextSection, ...(nextSep > 0 ? [nextSep] : [])].sort((a, b) => a - b);
+  const end = candidates[0];
+  return (end ? after.slice(0, end) : after).trim();
+};
+
+/** Extract the brief transcript part (everything after ---) */
+const briefOf = (text: string): string => {
+  const idx = text.indexOf(SEPARATOR);
+  if (idx < 0) return "";
+  return text.slice(idx + SEPARATOR.length).trim();
+};
+
+/** Merge a header section */
+const mergeHeaderSection = (header: string, prev: string, fresh: string): string => {
+  // Outstanding Context is volatile -- always use fresh only
+  if (header === "Outstanding Context") return fresh;
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+
+  // Files And Changes: merge by category (Modified/Created/Read), dedup paths
+  if (header === "Files And Changes") {
+    return mergeFileLines(prev, fresh);
+  }
+
+  // Session Goal, User Preferences: line-level dedup, cap
+  const isClean = (l: string) => l.startsWith("- ") && !l.includes("<skill") && !l.includes("</skill");
+  const prevLines = prev.split("\n").filter(isClean);
+  const freshLines = fresh.split("\n").filter(isClean);
+  const combined = [...new Set([...prevLines, ...freshLines])];
+  const CAP = header === "Session Goal" ? 8 : header === "Commits" ? 8 : 15;
+  const capped = combined.length > CAP ? combined.slice(-CAP) : combined;
+  if (capped.length === 0) return "";
+  return `[${header}]\n${capped.join("\n")}`;
+};
+
+/** Merge Files And Changes by category, dedup paths across compactions */
+const mergeFileLines = (prev: string, fresh: string): string => {
+  const categories = ["Modified", "Created", "Read"] as const;
+  const merged: Record<string, Set<string>> = {};
+  for (const cat of categories) merged[cat] = new Set();
+
+  // Parse "- Modified: a, b, c (+N more)" lines from both prev and fresh
+  for (const text of [prev, fresh]) {
+    for (const line of text.split("\n")) {
+      for (const cat of categories) {
+        const prefix = `- ${cat}: `;
+        if (!line.startsWith(prefix)) continue;
+        let rest = line.slice(prefix.length);
+        // Strip "(+N more)" suffix
+        rest = rest.replace(/\s*\(\+\d+ more\)\s*$/, "");
+        for (const p of rest.split(",")) {
+          const trimmed = p.trim();
+          if (trimmed) merged[cat].add(trimmed);
+        }
+      }
+    }
+  }
+
+  // Dedup: if already in Modified, drop from Created (file existed before)
+  for (const p of merged.Modified) merged.Created.delete(p);
+
+  const cap = (set: Set<string>, limit: number) => {
+    const arr = [...set];
+    if (arr.length <= limit) return arr.join(", ");
+    return arr.slice(0, limit).join(", ") + ` (+${arr.length - limit} more)`;
+  };
+
+  const lines: string[] = [];
+  if (merged.Modified.size > 0) lines.push(`- Modified: ${cap(merged.Modified, 10)}`);
+  if (merged.Created.size > 0) lines.push(`- Created: ${cap(merged.Created, 10)}`);
+  if (merged.Read.size > 0) lines.push(`- Read: ${cap(merged.Read, 10)}`);
+  if (lines.length === 0) return "";
+  return `[Files And Changes]\n${lines.join("\n")}`;
+};
+
+const mergeBriefTranscript = (prev: string, fresh: string): string => {
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+  return prev + "\n\n" + fresh;
+};
+
+const mergePrevious = (prev: string, fresh: string): string => {
+  // Merge header sections
+  const headers = HEADER_NAMES
+    .map((header) => {
+      const freshSec = sectionOf(fresh, header);
+      const prevSec = sectionOf(prev, header);
+      return mergeHeaderSection(header, prevSec, freshSec);
+    })
+    .filter(Boolean);
+
+  // Merge brief transcript
+  const prevBrief = briefOf(prev);
+  const freshBrief = briefOf(fresh);
+  const mergedBrief = mergeBriefTranscript(prevBrief, freshBrief);
+
+  const parts: string[] = [];
+  if (headers.length > 0) {
+    parts.push(headers.join("\n\n"));
+  }
+  if (mergedBrief) {
+    parts.push(capBrief(mergedBrief));
+  }
+
+  return parts.join(SEPARATOR);
+};
+
+export const compile = async (input: CompileInput): Promise<string> => {
+  const blocks = filterNoise(normalize(input.messages));
+  const settings = await loadSettings();
+  const data = buildSections({ blocks, extraction: settings.extraction });
+  const fresh = formatSummary(data);
+  // Strip any legacy RECALL_NOTE baked into prev summary (pre-fix format)
+  // so merge doesn't re-stack it inside the brief.
+  const prev = input.previousSummary
+    ? stripRecallNote(input.previousSummary)
+    : undefined;
+  const merged = prev ? mergePrevious(prev, fresh) : fresh;
+  if (!merged) return "";
+  return merged + SEPARATOR + RECALL_NOTE;
+};
+
+const stripRecallNote = (text: string): string => {
+  // Remove trailing RECALL_NOTE (and any separators surrounding it) if present.
+  // Handles both current format (---\n\nNOTE) and bare trailing NOTE.
+  const idx = text.lastIndexOf(RECALL_NOTE);
+  if (idx < 0) return text;
+  return text.slice(0, idx).replace(/\s*(?:\n\n---\n\n)?\s*$/, "").trimEnd();
+};

package/src/core/tool-args.ts

@@ -0,0 +1,14 @@
+export const extractPath = (args: Record<string, unknown>): string | null => {
+  for (const key of ["path", "file_path", "filePath", "file"]) {
+    if (typeof args[key] === "string") return args[key] as string;
+  }
+  return null;
+};
+
+export const summarizeToolArgs = (args: Record<string, unknown>): string => {
+  const path = extractPath(args);
+  if (path) return `path=${path}`;
+  if (typeof args.command === "string") return `command=${args.command}`;
+  if (typeof args.query === "string") return `query=${args.query}`;
+  return Object.keys(args).join(", ");
+};

package/src/details.ts

@@ -0,0 +1,7 @@
+export interface PiVccCompactionDetails {
+  compactor: "pi-vcc";
+  version: number;
+  sections: string[];
+  sourceMessageCount: number;
+  previousSummaryUsed: boolean;
+}