@monotykamary/pi-vcc 0.3.17 → 0.4.0

package/README.md

@@ -210,7 +210,7 @@ pi-vcc is one of four compaction approaches in the AI coding-agent ecosystem. He
 - **Error resolution detection** — tsc errors in `[Outstanding Context]` are tagged `[RESOLVED]` when the file they reference was subsequently edited, letting the model skip stale errors.
 - **Task-boundary-aware cut** — compaction splits at complete conversational turns, not mid-tool-call. If the assistant's response is in-flight (unmatched tool calls), the cut pushes back to keep the whole turn in the tail.
 - **Structured anchors** — `[Anchors]` section lists commit hashes, error IDs, and key file paths for zero-tool-call recall. The model can find references at a glance instead of calling `vcc_recall`.
-- **Per-model and global compaction thresholds** — configure different `reserveTokens` or `compactPercent` per model and globally, so models with different context windows compact at the right time. Works in both directions: compact earlier for small-context models, compact later for large-context ones. Applies to both pi-vcc and pi-core compaction. Proactive triggering on `agent_end` and `model_select` events.
+- **Per-model and global compaction thresholds** — configure different `reserveTokens` or `compactPercent` per model and globally, so models with different context windows compact at the right time. Proactive triggering on `agent_end` and `model_select` events compacts earlier for small-context models. Applies to both pi-vcc and pi-core compaction.
 
 ## Install
 
@@ -579,14 +579,15 @@ Config lives at `~/.pi/agent/pi-vcc-config.json` (auto-scaffolded on first load
 
 Pi-core's auto-compaction triggers when `contextTokens > contextWindow − reserveTokens`. The global `reserveTokens` (default 16384) is one-size-fits-all — but different models have very different context windows and cost profiles.
 
-Pi-vcc's thresholds control compaction timing in **both directions**, and work at both the per-model and global level:
+Pi-vcc's thresholds provide proactive compaction at both the per-model and global level:
 
 | Direction | How it works |
 |---|---|
-| **Compact later** (model can handle more context) | `session_before_compact` cancels compaction when context hasn't crossed the model's threshold. The global threshold might trigger compaction prematurely for a model with a large context window. |
 | **Compact earlier** (model needs compaction sooner) | `agent_end` and `model_select` proactively trigger compaction when context exceeds the model's threshold but hasn't hit the global threshold yet. The `globalThreshold` also proactively triggers for unmatched models. |
 
-This works regardless of whether pi-vcc or pi-core handles the actual summary (`overrideDefaultCompaction` true or false) — compaction thresholds control the *when*, not the *how*.
+Previously, a "compact later" direction was implemented by cancelling compaction in `session_before_compact` when context was below the per-model threshold. This guard was removed because `session_before_compact` carries no reason field — manual `/compact` and auto-compaction are indistinguishable (both have `customInstructions: undefined`), so the guard was blocking explicit user compaction requests.
+
+The proactive trigger handles the "compact earlier" direction. If pi-core's global threshold fires before the per-model threshold is crossed, the compaction proceeds — slightly premature from the per-model threshold's perspective, but preferable to blocking an explicit user action.
 
 Key matching order: exact `"provider/modelId"` → `"modelId"` → `globalThreshold` → pi-core's global setting.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-vcc",
-  "version": "0.3.17",
+  "version": "0.4.0",
   "description": "Algorithmic conversation compactor for pi - transcript-preserving structured summaries, no LLM calls",
   "main": "index.ts",
   "keywords": [

package/src/core/build-sections.ts

@@ -224,34 +224,16 @@ const extractOutstandingContext = (blocks: NormalizedBlock[]): string[] => {
 
 const formatFileActivityFromUnified = (data: import("../extract/shared-symbols").UnifiedExtractResult): string[] => {
   const act = data.fileActivity;
-  const maxSymbolsPerFile = 4;
-
-  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 formatCategory = (label: string, set: Set<string>): string | null => {
     if (set.size === 0) return null;
     const arr = [...set];
-    const annotated: string[] = [];
-
-    for (const p of arr.slice(0, 10)) {
-      const syms = act.symbols.get(p);
-      if (syms && syms.length > 0) {
-        const sigs = syms.slice(0, maxSymbolsPerFile).join(", ");
-        const suffix = syms.length > maxSymbolsPerFile ? `, +${syms.length - maxSymbolsPerFile} more` : "";
-        annotated.push(`${p} (${sigs}${suffix})`);
-      } else {
-        annotated.push(p);
-      }
-    }
+    const kept = arr.slice(0, 10);
 
     if (arr.length > 10) {
-      return `${label}: ${annotated.join(", ")} (+${arr.length - 10} more)`;
+      const omitted = arr.slice(10);
+      return `${label}: ${kept.join(", ")}, +recall: ${omitted.join(", ")}`;
     }
-    return `${label}: ${annotated.join(", ")}`;
+    return `${label}: ${kept.join(", ")}`;
   };
 
   const lines: string[] = [];
@@ -271,118 +253,22 @@ const formatTypeCatalogFromUnified = (data: import("../extract/shared-symbols").
   let totalSigs = 0;
   const MAX_TOTAL_SIGS = 30;
 
-  for (const entry of catalog) {
+  const omittedFiles: string[] = [];
+  for (let i = 0; i < catalog.length; i++) {
+    const entry = catalog[i];
     if (totalSigs >= MAX_TOTAL_SIGS) {
-      lines.push("(more signatures omitted)");
-      break;
+      omittedFiles.push(entry.file);
+      continue;
     }
-    const tag = entry.modified ? "[modified]" : "[read]";
-    lines.push(`${entry.file} ${tag}:`);
+    lines.push(`${entry.file}:`);
     for (const sig of entry.signatures) {
       if (totalSigs >= MAX_TOTAL_SIGS) break;
       lines.push(`  ${sig}`);
       totalSigs++;
     }
   }
-
-  return lines;
-};
-
-// User messages that are purely confirmatory — skip these for "Working on"
-const CONFIRMATORY_USER_RE =
-  /^(ok|okay|yes|yeah|yep|sure|great|thanks|thx|nice|looks? good|works?|perfect|done|thanks!*|got it|i see|lgtm|awesome)\b/i;
-
-/**
- * Extract current working status from the tail of the conversation.
- * Returns up to 3 lines: current focus, last action, next steps.
- */
-const extractCurrentStatus = (blocks: NormalizedBlock[]): string[] => {
-  const items: string[] = [];
-  const tail = blocks.slice(-20);
-
-  // 1. Current focus: last substantive (non-confirmatory) user message
-  for (let i = tail.length - 1; i >= 0; i--) {
-    const b = tail[i];
-    if (b.kind !== "user") continue;
-    const text = b.text.trim();
-    if (text.length < 10 || CONFIRMATORY_USER_RE.test(text)) continue;
-    items.push(`Working on: ${clip(text, 120)}`);
-    break;
-  }
-
-  // 2. Last action: last tool call that modified/read a file
-  for (let i = tail.length - 1; i >= 0; i--) {
-    const b = tail[i];
-    if (b.kind === "tool_call") {
-      const path = extractPath(b.args);
-      if (path) {
-        const cmd = b.name.length > 80 ? `${b.name.slice(0, 77)}...` : b.name;
-        items.push(`Last action: ${cmd} "${clip(path, 80)}"`);
-        break;
-      }
-    }
-  }
-
-  // 3. Next steps: last agent text that mentions what to do next
-  for (let i = tail.length - 1; i >= 0; i--) {
-    const b = tail[i];
-    if (b.kind === "assistant" && b.text.trim().length > 20) {
-      const nextMatch = b.text.match(/(?:next|remaining|todo|still need|what.*left|following)/i);
-      if (nextMatch) {
-        items.push(`Next: ${clip(b.text.trim(), 120)}`);
-        break;
-      }
-    }
-  }
-
-  return items.slice(0, 3);
-};
-
-/**
- * Extract structured reference anchors from already-built section data.
- * These let the model self-serve common lookups without calling vcc_recall.
- */
-const extractAnchors = (data: SectionData): string[] => {
-  const lines: string[] = [];
-
-  // Commit hashes
-  const commitHashes: string[] = [];
-  for (const line of data.commits) {
-    const hashMatch = line.match(/^-\s*([a-f0-9]{7,40}):/);
-    if (hashMatch) commitHashes.push(hashMatch[1]);
-  }
-  if (commitHashes.length > 0) {
-    lines.push(`commits: ${commitHashes.join(", ")}`);
-  }
-
-  // Error IDs from outstanding context
-  const errorIds: string[] = [];
-  for (const line of data.outstandingContext) {
-    const tscMatch = line.match(/TS(\d{4,5})/);
-    if (tscMatch) errorIds.push(`TS${tscMatch[1]}`);
-  }
-  if (errorIds.length > 0) {
-    lines.push(`errors: ${[...new Set(errorIds)].join(", ")}`);
-  }
-
-  // Key file paths from Files And Changes
-  const filePaths: string[] = [];
-  for (const line of data.filesAndChanges) {
-    const categoryMatch = line.match(/^-\s*(?:Modified|Created|Read):\s*(.*)/);
-    if (!categoryMatch) continue;
-    const pathPart = categoryMatch[1]
-      .replace(/\s*\([^)]*\)/g, "")
-      .replace(/\s*\(\+\d+ more\)\s*$/, "");
-    for (const p of pathPart.split(",")) {
-      const trimmed = p.trim();
-      if (trimmed) filePaths.push(trimmed);
-    }
-  }
-  if (filePaths.length > 0) {
-    const display = filePaths.length <= 15
-      ? filePaths.join(", ")
-      : `${filePaths.slice(0, 12).join(", ")} (+${filePaths.length - 12} more)`;
-    lines.push(`files: ${display}`);
+  if (omittedFiles.length > 0) {
+    lines.push(`(${omittedFiles.length} more files with signatures omitted)`);
   }
 
   return lines;
@@ -417,15 +303,10 @@ export const buildSections = (input: BuildSectionsInput): SectionData => {
     userPreferences,
     typeCatalog: formatTypeCatalogFromUnified(fileAndSymbols),
     symbolChanges: fileAndSymbols.symbolChanges,
-    currentStatus: extractCurrentStatus(blocks),
     turnSummaries,
-    anchors: [],  // populated after initial section data is built
     briefTranscript: stringifyBrief(briefSections),
     transcriptEntries: sectionsToTranscript(briefSections),
   };
 
-  // Anchors depend on other sections, so extract after building them
-  result.anchors = extractAnchors(result);
-
   return result;
 };

package/src/core/format.ts

@@ -43,20 +43,15 @@ export const capBrief = (text: string): string => {
   // Find first section header to avoid cutting mid-section
   const firstHeader = kept.findIndex((l) => /^\[.+\]/.test(l));
   const clean = firstHeader > 0 ? kept.slice(firstHeader) : kept;
-  return `...(${omitted} earlier lines omitted)\n\n${clean.join("\n")}`;
+  const crumbLine = `...(${omitted} earlier lines omitted)`;
+  return `${crumbLine}\n\n${clean.join("\n")}`;
 };
 
-export const RECALL_NOTE =
-  "Use `vcc_recall` to search for prior work, decisions, and context from before this summary. " +
-  "Do not redo work already completed.";
-
-/**
- * Format the summary with cache-friendly section ordering.
+/** Format the summary with cache-friendly section ordering.
  *
  * Stable (merged/accumulated) sections come first so the prompt prefix
  * stays cacheable across compactions. Volatile (always-fresh) sections
- * come last.
- */
+ * come last. */
 export const formatSummary = (
   data: SectionData,
 ): string => {
@@ -66,14 +61,12 @@ export const formatSummary = (
     section("User Preferences", data.userPreferences),
     section("Files And Changes", data.filesAndChanges),
     section("Commits", data.commits),
-    section("Anchors", data.anchors),
   ].filter(Boolean);
 
   const volatileSections = [
     section("Type Catalog", data.typeCatalog),
     section("Outstanding Context", data.outstandingContext),
     section("Earlier Turns", data.turnSummaries),
-    section("Current Status", data.currentStatus),
   ].filter(Boolean);
 
   // All header sections (stable + volatile) form the header block
@@ -91,8 +84,5 @@ export const formatSummary = (
 
   let result = wrapLongLines(parts.join("\n\n---\n\n"));
 
-  // NOTE: RECALL_NOTE is intentionally NOT appended here.
-  // It is appended once by `compile()` at the very end, after merge-with-previous,
-  // to avoid the note compounding inside the brief transcript across compactions.
   return result;
 };

package/src/core/summarize.ts

@@ -3,7 +3,7 @@ import type { FileOps } from "../types";
 import { normalize } from "./normalize";
 import { filterNoise } from "./filter-noise";
 import { buildSections } from "./build-sections";
-import { formatSummary, capBrief, RECALL_NOTE, wrapLongLines } from "./format";
+import { formatSummary, capBrief, wrapLongLines } from "./format";
 
 export interface CompileInput {
   messages: Message[];
@@ -17,11 +17,9 @@ const HEADER_NAMES = [
   "User Preferences",
   "Files And Changes",
   "Commits",
-  "Anchors",
   "Type Catalog",
   "Outstanding Context",
   "Earlier Turns",
-  "Current Status",
 ];
 
 const SEPARATOR = "\n\n---\n\n";
@@ -31,7 +29,8 @@ const HANDFOFF_PREAMBLE =
   "This summary captures work done before the most recent messages in this session. " +
   "Read it to pick up context — this is work already in progress. " +
   "Do not recap what was done, do not ask what to do next. " +
-  "Continue directly where you left off.";
+  "Continue directly where you left off. " +
+  "Use `vcc_recall` to search for prior work, decisions, and context from before this summary.";
 
 /** Extract a named section from summary text */
 const sectionOf = (text: string, header: string): string => {
@@ -57,27 +56,67 @@ const briefOf = (text: string): string => {
   return text.slice(idx + SEPARATOR.length).trim();
 };
 
+/**
+ * Extract searchable keywords from a section line for breadcrumb trails.
+ *
+ * Deterministic: same input always produces the same breadcrumb.
+ * Idempotent: the breadcrumb is a pure function of the line text.
+ */
+const extractBreadcrumb = (line: string): string => {
+  const text = line.replace(/^\s*-\s*/, "").trim();
+  if (!text) return "";
+  // "edited auth.ts" → "auth.ts"
+  const fileMatch = text.match(/(?:edited |read |wrote |created |deleted )?(\S+\.\w{1,12})/);
+  if (fileMatch) return fileMatch[1];
+  // "Fix login bug → ..." → first few words before →
+  const beforeArrow = text.split("\u2192")[0].trim();
+  const words = beforeArrow.split(/\s+/).filter(w => w.length > 2).slice(0, 3);
+  if (words.length > 0) return words.join(" ");
+  // fallback: first content word
+  const first = text.split(/\s+/).find(w => w.length > 2);
+  return first ?? "";
+};
+
 /** Merge a header section */
 const mergeHeaderSection = (header: string, prev: string, fresh: string): string => {
-  // Outstanding Context, Type Catalog, and Current Status are volatile -- always use fresh only
-  if (header === "Outstanding Context" || header === "Type Catalog" || header === "Current Status" || header === "Anchors") return fresh;
-  if (!prev) return fresh;
-  if (!fresh) return prev;
-
-  // Files And Changes: merge by category (Modified/Created/Read), dedup paths
+  // Outstanding Context, Type Catalog are volatile -- always use fresh only
+  if (header === "Outstanding Context" || header === "Type Catalog") return fresh;
+  if (!prev && !fresh) return "";
+  // Files And Changes: always run through merge (even when only prev
+  // has content) so the cap +recall breadcrumbs are applied.
   if (header === "Files And Changes") {
     return mergeFileLines(prev, fresh);
   }
 
-  // Session Goal, User Preferences: line-level dedup, cap
+  // Session Goal, User Preferences, Commits, Earlier Turns: line-level dedup, cap
   const isClean = (l: string) => l.startsWith("- ") && !l.includes("<skill") && !l.includes("</skill");
+  // ...recall: breadcrumb lines from prior compactions are preserved as-is,
+  // not re-processed or capped. They survive across compactions.
+  const isRecallBreadcrumb = (l: string) => l.startsWith("- ...recall:");
   const prevLines = prev.split("\n").filter(isClean);
   const freshLines = fresh.split("\n").filter(isClean);
-  const combined = [...new Set([...prevLines, ...freshLines])];
+  const prevBreadcrumbs = prev.split("\n").filter(isRecallBreadcrumb);
+  const freshBreadcrumbs = fresh.split("\n").filter(isRecallBreadcrumb);
+  const allBreadcrumbs = [...new Set([...prevBreadcrumbs, ...freshBreadcrumbs])];
+  const contentLines = [...new Set([...prevLines.filter(l => !isRecallBreadcrumb(l)), ...freshLines.filter(l => !isRecallBreadcrumb(l))])];
   const CAP = header === "Session Goal" ? 8 : header === "Commits" ? 8 : header === "Earlier Turns" ? 15 : 15;
-  const capped = combined.length > CAP ? combined.slice(-CAP) : combined;
-  if (capped.length === 0) return "";
-  return `[${header}]\n${capped.join("\n")}`;
+  if (contentLines.length > CAP) {
+    const kept = contentLines.slice(-CAP);
+    const dropped = contentLines.slice(0, contentLines.length - CAP);
+    const crumbs = dropped.map(extractBreadcrumb).filter(Boolean);
+    const headerLine = `[${header}]`;
+    // Merge new crumbs with existing breadcrumbs (dedup by extracting terms)
+    const allCrumbs = crumbs.length > 0 ? [...allBreadcrumbs, `- ...recall: ${crumbs.join(", ")}`] : allBreadcrumbs;
+    if (allCrumbs.length > 0) {
+      return `${headerLine}\n${allCrumbs.join("\n")}\n${kept.join("\n")}`;
+    }
+    return `${headerLine}\n${kept.join("\n")}`;
+  }
+  if (contentLines.length === 0 && allBreadcrumbs.length === 0) return "";
+  const parts: string[] = [];
+  if (allBreadcrumbs.length > 0) parts.push(...allBreadcrumbs);
+  if (contentLines.length > 0) parts.push(...contentLines);
+  return `[${header}]\n${parts.join("\n")}`;
 };
 
 /** Merge Files And Changes by category, dedup paths across compactions */
@@ -88,7 +127,9 @@ const mergeFileLines = (prev: string, fresh: string): string => {
 
   // Parse "- Modified: a, b, c (+N more)" lines from both prev and fresh
   // Also handle symbol-annotated format: "- Modified: a (fn1, fn2), b"
+  // Also handle breadcrumb format: "path1, +recall: path2, path3"
   for (const text of [prev, fresh]) {
+    if (!text) continue;
     for (const line of text.split("\n")) {
       for (const cat of categories) {
         const prefix = `- ${cat}: `;
@@ -98,8 +139,12 @@ const mergeFileLines = (prev: string, fresh: string): string => {
         rest = rest.replace(/\s*\([^)]*\)/g, "");
         // Strip "(+N more)" suffix
         rest = rest.replace(/\s*\(\+\d+ more\)\s*$/, "");
+        // Strip breadcrumb marker so paths after it are parsed
+        rest = rest.replace(/,\s*\+recall:\s*/, ", ");
         for (const p of rest.split(",")) {
           const trimmed = p.trim();
+          // Skip breadcrumb markers that survived the replace
+          if (trimmed.startsWith("+recall:")) continue;
           if (trimmed) merged[cat].add(trimmed);
         }
       }
@@ -112,7 +157,9 @@ const mergeFileLines = (prev: string, fresh: string): string => {
   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 kept = arr.slice(0, limit);
+    const omitted = arr.slice(limit);
+    return kept.join(", ") + `, +recall: ${omitted.join(", ")}`;
   };
 
   const lines: string[] = [];
@@ -166,14 +213,43 @@ export const compile = (input: CompileInput): string => {
     : undefined;
   const merged = prev ? mergePrevious(prev, fresh) : fresh;
   if (!merged) return "";
-  const body = merged + SEPARATOR + RECALL_NOTE;
+  const body = merged;
   return wrapLongLines(HANDFOFF_PREAMBLE + "\n\n" + body);
 };
 
 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();
+  // Strip leading preamble (HANDFOFF_PREAMBLE) that compile() prepends to every output.
+  // When the output from one compaction becomes the previousSummary for the next,
+  // the preamble must be removed so mergePrevious only sees the actual sections.
+  //
+  // Also handles legacy format where RECALL_NOTE was a trailing --- block
+  // (before the preamble merge). Both shapes can appear in the same text
+  // (old format had a leading preamble AND a trailing RECALL_NOTE). Both must
+  // be stripped so the merge only sees clean section data.
+
+  let result = text;
+
+  // 1. Leading preamble (current format): "This summary captures..."
+  if (result.startsWith("This summary captures work done before")) {
+    // Find the end of the preamble paragraph (first section header or double newline)
+    const headerStart = result.indexOf("[");
+    if (headerStart > 0) {
+      result = result.slice(headerStart).trim();
+    } else {
+      const doubleNL = result.indexOf("\n\n");
+      if (doubleNL > 0) result = result.slice(doubleNL + 2).trim();
+    }
+  }
+
+  // 2. Trailing legacy RECALL_NOTE (pre-preamble-merge format)
+  //    Old format appended RECALL_NOTE as a separate --- block at the end.
+  //    After step 1 strips the leading preamble, the trailing block survives.
+  //    Must be stripped so it doesn't get merged into the brief transcript.
+  const legacyRecall = "Use `vcc_recall` to search for prior work, decisions, and context from before this summary.";
+  const legacyIdx = result.lastIndexOf(legacyRecall);
+  if (legacyIdx > 0) {
+    result = result.slice(0, legacyIdx).replace(/\s*(?:\n\n---\n\n)?\s*$/, "").trimEnd();
+  }
+
+  return result;
 };

package/src/sections.ts

@@ -11,12 +11,8 @@ export interface SectionData {
   typeCatalog: string[];
   /** Symbol-level changes (function/type/class names per file) */
   symbolChanges: SymbolRef[];
-  /** Current working context: what's being worked on, last action, next steps */
-  currentStatus: string[];
   /** Per-turn one-liner summaries for the HCA zone (heaviest compression, oldest turns) */
   turnSummaries: string[];
-  /** Structured reference anchors for zero-tool-call recall */
-  anchors: string[];
   briefTranscript: string;
   /** Structured transcript entries (verbose object format) */
   transcriptEntries: TranscriptEntry[];