@monotykamary/pi-vcc 0.4.0 → 0.5.0

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@monotykamary/pi-vcc",
-  "version": "0.3.17",
+  "version": "0.4.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@monotykamary/pi-vcc",
-      "version": "0.3.17",
+      "version": "0.4.1",
       "devDependencies": {
         "knip": "6.14.1",
         "typescript": "6.0.3"

package/package.json

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

package/src/core/brief.ts

@@ -2,6 +2,7 @@ import type { NormalizedBlock } from "../types";
 import { clip, firstLine } from "./content";
 import { extractPath } from "./tool-args";
 import { collapseSkillText } from "./skill-collapse";
+import { KEY_STOPS, refineBreadcrumbKey } from "./causal-keys";
 
 const TRUNCATE_USER = 256;
 const TRUNCATE_ASSISTANT = 200;
@@ -409,13 +410,203 @@ const shortenPath = (p: string): string => {
   return parts.length > 2 ? parts.slice(-2).join("/") : p;
 };
 
+// ── causal extraction ──
+// Marker-based extraction: scan for specific phrases that signal cause or
+// resolution, then extract a bounded fragment after the marker.
+//
+// Why markers instead of regex patterns?
+// 1. No backtracking risk — indexOf + linear char scan is O(n) worst case.
+//    Regex with lazy quantifiers + alternation ([^.,;!?]+?)(?:[.,;!?]|$)
+//    can theoretically backtrack, though JS engines limit this in practice.
+// 2. Bounded by construction — FRAGMENT_MAX hard cap, no unbounded capture.
+// 3. Easy to extend — add a string to the list, no regex syntax to debug.
+// 4. Multi-sentence aware — tries full text first, then per-sentence.
+
+// Cause markers: phrases that signal "here comes the reason/problem".
+// Ordered from most specific to least specific; first match wins.
+const CAUSE_MARKERS: readonly string[] = [
+  "the issue is",
+  "the problem is",
+  "the problem was",
+  "the bug is",
+  "the bug was",
+  "the cause is",
+  "root cause:",
+  "root cause is",
+  "the reason is",
+  "fails because",
+  "fails when",
+  "fails due to",
+  "crashes because",
+  "crashes when",
+  "crashes due to",
+  "breaks because",
+  "breaks when",
+  "breaks due to",
+  "because ",
+  "since ",
+  "due to ",
+  "missing ",
+  "lacking ",
+  "lack of ",
+  "absence of ",
+  "can't ",
+  "cannot ",
+  "not properly ",
+  "not correctly ",
+  "not validating ",
+  "not returning ",
+  "not handling ",
+  "not releasing ",
+  "not checking ",
+  "wrong ",
+  "incorrect ",
+  "stale ",
+  "outdated ",
+  "unhandled ",
+  "uncaught ",
+];
+
+// Resolution markers: phrases that signal "here comes the fix/action".
+// Ordered from most specific to least specific; first match wins.
+const RESOLUTION_MARKERS: readonly string[] = [
+  "fix this by",
+  "fix it by",
+  "resolve this by",
+  "resolve it by",
+  "resolve by",
+  "handle this by",
+  "handle by",
+  "address this by",
+  "address by",
+  "by adding",
+  "by creating",
+  "by implementing",
+  "by introducing",
+  "by applying",
+  "by inserting",
+  "by using",
+  "by swapping",
+  "by migrating",
+  "by isolating",
+  "by splitting",
+  "by extracting",
+  "by replacing",
+  "by refactoring",
+  "by wrapping",
+  "by moving",
+  "by removing",
+  "added ",
+  "created ",
+  "implemented ",
+  "introduced ",
+  "applied ",
+  "inserted ",
+  "changed to",
+  "updated to",
+  "switched to",
+  "migrated to",
+  "replaced with",
+  "replaced by",
+  "refactored to",
+  "extracted into",
+  "set up ",
+  "configured ",
+  "enabled ",
+  "swapped ",
+  "isolated ",
+  "splitting ",
+  "split ",
+  "wrapped ",
+  "guarded ",
+  "moved ",
+  "removed ",
+];
+
+// Maximum chars for a causal fragment — hard cap prevents unbounded capture.
+const FRAGMENT_MAX = 60;
+// Maximum chars for a causal breadcrumb key — keeps the ...recall line bounded.
+const CAUSAL_BREADCRUMB_MAX = 40;
+
+// Characters that terminate a causal fragment.
+const SENTINEL_CHARS = new Set([...
+  ",.;!?\n"
+]);
+
+/**
+ * Extract a bounded fragment starting after the first matching marker.
+ * Stops at the first sentinel character or FRAGMENT_MAX chars, whichever
+ * comes first. O(n) single pass — indexOf + linear scan, no regex.
+ */
+const extractFragment = (
+  text: string,
+  markers: readonly string[],
+): string | null => {
+  const lower = text.toLowerCase();
+  for (const marker of markers) {
+    const idx = lower.indexOf(marker);
+    if (idx < 0) continue;
+    const start = idx + marker.length;
+    if (start >= text.length) continue;
+
+    let end = start;
+    while (end < text.length && end - start < FRAGMENT_MAX) {
+      if (SENTINEL_CHARS.has(text[end])) break;
+      end++;
+    }
+    const fragment = text.slice(start, end).trim();
+    if (fragment.length < 4) continue;
+    return fragment;
+  }
+  return null;
+};
+
+/**
+ * Extract a causal fragment from assistant text.
+ * Returns { cause, resolution } where each is a short string or null.
+ *
+ * Deterministic: same text always produces the same result.
+ * O(n): indexOf + linear char scan per marker; no regex backtracking.
+ * Bounded: fragments are capped at CAUSAL_BREADCRUMB_MAX chars.
+ */
+export const extractCausalChain = (
+  text: string,
+): { cause: string | null; resolution: string | null } => {
+  // Try full text first (markers can span sentence boundaries)
+  let cause = extractFragment(text, CAUSE_MARKERS);
+  let resolution = extractFragment(text, RESOLUTION_MARKERS);
+
+  // If we didn't find both, also try per-sentence (handles cases like
+  // "The issue is a race condition. I fixed it by adding a mutex."
+  // where cause and resolution are in different sentences but the
+  // resolution marker "it by" doesn't match because "it" is too far
+  // from the full text's start).
+  if (!cause || !resolution) {
+    const sentences = text.split(/[.!?]/).filter(s => s.trim().length > 3);
+    for (const sentence of sentences) {
+      if (!cause) cause = extractFragment(sentence, CAUSE_MARKERS);
+      if (!resolution) resolution = extractFragment(sentence, RESOLUTION_MARKERS);
+      if (cause && resolution) break;
+    }
+  }
+
+  return {
+    cause: cause ? clip(cause, CAUSAL_BREADCRUMB_MAX) : null,
+    resolution: resolution ? clip(resolution, CAUSAL_BREADCRUMB_MAX) : null,
+  };
+};
+
 /**
  * Synthesize a one-line summary for a conversational turn.
  * No LLM — purely algorithmic compression.
+ *
+ * V2: includes causal information when available (cause → resolution → actions).
+ * Falls back to V1 format when no causal chain is found.
  */
 const synthesizeTurnSummary = (
   userText: string | null,
   toolActions: string[],
+  causalChain: { cause: string | null; resolution: string | null } = { cause: null, resolution: null },
 ): string => {
   const parts: string[] = [];
 
@@ -424,6 +615,13 @@ const synthesizeTurnSummary = (
     parts.push(clip(userText, 50));
   }
 
+  // Causal chain: cause → resolution (before actions)
+  const hasCausal = causalChain.cause || causalChain.resolution;
+  if (hasCausal) {
+    if (causalChain.cause) parts.push(causalChain.cause);
+    if (causalChain.resolution) parts.push(causalChain.resolution);
+  }
+
   // Key actions — dedup and cap
   const uniqueActions = [...new Set(toolActions)].slice(0, 5);
   if (uniqueActions.length > 0) {
@@ -442,6 +640,36 @@ const synthesizeTurnSummary = (
   return parts.join(" \u2192 ") || "(no actions)";
 };
 
+/**
+ * Build a causal breadcrumb for a turn summary line.
+ * Format: "file|resolution-key" instead of just "file" or keywords.
+ *
+ * Deterministic: same input always produces the same breadcrumb.
+ * Idempotent: the breadcrumb is a pure function of the line text and causal chain.
+ */
+const buildCausalBreadcrumb = (
+  turnSummary: string,
+  causalChain: { cause: string | null; resolution: string | null },
+): string => {
+  // Extract file from action part (after →)
+  const fileMatch = turnSummary.match(/(?:edited |read |wrote |created |deleted )?([^\s→.]+\.\w{1,12})/);
+  const file = fileMatch ? shortenPath(fileMatch[1]) : null;
+
+  // Build resolution key from causal chain using stop-word-aware refinement
+  const resolutionKey = causalChain.resolution
+    ? refineBreadcrumbKey(causalChain.resolution)
+    : null;
+
+  if (file && resolutionKey) return `${file}|${resolutionKey}`;
+  if (resolutionKey) return resolutionKey;
+  // Fallback: V1 breadcrumb logic
+  const beforeArrow = turnSummary.split("\u2192")[0].trim();
+  const words = beforeArrow.split(/\s+/).filter(w => w.length > 2).slice(0, 3);
+  if (words.length > 0) return words.join(" ");
+  if (file) return file;
+  return "";
+};
+
 /**
  * Identify conversational turns and produce one-liner summaries.
  *
@@ -449,19 +677,29 @@ const synthesizeTurnSummary = (
  * responses, tool calls, and tool results until the next user/bash block.
  * This is the HCA zone — the heaviest compression layer that covers turns
  * that would otherwise fall off the brief transcript's capBrief cutoff.
+ *
+ * V2: extracts causal chains from assistant text and includes them in
+ * turn summaries. Causal breadcrumbs are emitted for the ...recall system.
  */
 export const identifyTurns = (blocks: NormalizedBlock[]): TurnInfo[] => {
   const turns: TurnInfo[] = [];
   let currentUserText: string | null = null;
   const toolActions: string[] = [];
+  const assistantTexts: string[] = [];
 
   const flush = () => {
     if (currentUserText === null && toolActions.length === 0) return;
+
+    // Extract causal chain from collected assistant text in this turn
+    const combinedAssistant = assistantTexts.join(" ");
+    const causalChain = extractCausalChain(combinedAssistant);
+
     turns.push({
-      summary: synthesizeTurnSummary(currentUserText, toolActions),
+      summary: synthesizeTurnSummary(currentUserText, toolActions, causalChain),
     });
     currentUserText = null;
     toolActions.length = 0;
+    assistantTexts.length = 0;
   };
 
   for (const b of blocks) {
@@ -472,6 +710,12 @@ export const identifyTurns = (blocks: NormalizedBlock[]): TurnInfo[] => {
         : `$ ${compressBash(b.command)}`;
       continue;
     }
+    if (b.kind === "assistant") {
+      // Collect assistant text for causal extraction
+      if (b.text && b.text.trim().length > 0) {
+        assistantTexts.push(b.text.trim());
+      }
+    }
     if (b.kind === "tool_call") {
       if (!b.name || b.name.trim() === "") continue;
       const path = extractPath(b.args);

package/src/core/causal-keys.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared stop words and key refinement for causal breadcrumb extraction.
+ *
+ * Used by both brief.ts (turn summary key generation) and summarize.ts
+ * (breadcrumb extraction from capped lines) to ensure consistent key output.
+ */
+
+// Stop words filtered out when building breadcrumb keys.
+// These carry no causal signal and would bloat the key.
+export const KEY_STOPS = new Set([
+  // Articles, pronouns, demonstratives
+  "the", "a", "an", "this", "that", "these", "those", "it", "its",
+  // Be-verbs, auxiliaries
+  "is", "was", "are", "were", "been", "being",
+  "has", "have", "had", "does", "do", "did",
+  "will", "would", "could", "should", "may", "might", "shall", "can",
+  // Prepositions
+  "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
+  "into", "through", "before", "after", "above", "below",
+  // Conjunctions, adverbs
+  "and", "but", "or", "not", "so", "yet",
+  "before", "after", "when", "where", "while", "during",
+  // Contextual filler that doesn't carry causal signal
+  "against", "into", "around", "before", "all",
+  // Marker remnant words: verbs from resolution markers that survive
+  // the extraction because the fragment starts right after the marker.
+  // E.g. "added session check" → we want "session-check", not "added-session-check".
+  "added", "adding", "created", "creating",
+  "applied", "applying", "inserted", "inserting",
+  "implemented", "implementing", "introduced", "introducing",
+  "using", "swapped", "swapping", "split", "splitting",
+  "migrated", "migrating", "isolated", "isolating",
+  "removed", "removing", "extracted", "extracting",
+  "replaced", "replacing", "refactored", "refactoring",
+  "wrapped", "wrapping", "guarded", "guarding",
+  "moved", "moving", "updated", "configured",
+  "enabled", "switched",
+]);
+
+/** Maximum content words in a breadcrumb key. */
+const KEY_MAX_WORDS = 3;
+
+/**
+ * Build a compact breadcrumb key from a raw fragment.
+ * Takes up to KEY_MAX_WORDS content words (skipping stop words), joined with "-".
+ */
+export const refineBreadcrumbKey = (fragment: string, maxChars = 40): string => {
+  const words = fragment.split(/\s+/);
+  const content: string[] = [];
+  for (const w of words) {
+    if (KEY_STOPS.has(w.toLowerCase())) continue;
+    content.push(w);
+    if (content.length >= KEY_MAX_WORDS) break;
+  }
+  return content.join("-") || fragment.slice(0, maxChars);
+};

package/src/core/summarize.ts

@@ -4,6 +4,7 @@ import { normalize } from "./normalize";
 import { filterNoise } from "./filter-noise";
 import { buildSections } from "./build-sections";
 import { formatSummary, capBrief, wrapLongLines } from "./format";
+import { refineBreadcrumbKey } from "./causal-keys";
 
 export interface CompileInput {
   messages: Message[];
@@ -65,9 +66,58 @@ const briefOf = (text: string): string => {
 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];
+
+  // V1: ...recall: breadcrumb — preserve as-is (they already carry causal keys)
+  if (text.startsWith("...recall:")) return text.slice("...recall:".length).trim();
+
+  // V2: causal breadcrumb from turn summary (contains →)
+  // Format: "goal → cause_fragment → resolution_fragment → tool_actions"
+  // The cause/resolution fragments are produced by extractCausalChain and
+  // are typically short phrases without a leading verb.
+  if (text.includes("\u2192")) {
+    const parts = text.split("\u2192").map(p => p.trim());
+
+    // Extract file from the action parts
+    const fileMatch = text.match(/(?:edited |read |wrote |created |deleted )?([^\s.]+\.\w{1,12})/);
+    const file = fileMatch ? fileMatch[1] : null;
+
+    // Identify structural parts: goal is first, tool actions are at the end
+    // (start with read/edited/ran or contain file paths).
+    // Middle parts are causal fragments.
+    const toolActionRe = /^(?:read|edited|wrote|created|deleted|ran)\s?/i;
+    const toolActionIdx = parts.findIndex(p => toolActionRe.test(p) || /\+\d+ more/.test(p));
+
+    // Causal parts are between goal (index 0) and tool actions
+    const causalEnd = toolActionIdx >= 0 ? toolActionIdx : parts.length;
+    const causalParts = parts.slice(1, causalEnd); // skip goal at index 0
+
+    // The last causal part before tool actions is the resolution fragment
+    // (from extractCausalChain). The one before that is the cause fragment.
+    const causePart = causalParts.length >= 2 ? causalParts[0] : null;
+    const resolutionPart = causalParts.length >= 1 ? causalParts[causalParts.length - 1] : null;
+
+    // Build breadcrumb: file|resolution-key
+    // Resolution key: content words from the resolution fragment, refined by shared key filter
+    if (resolutionPart) {
+      const resKey = refineBreadcrumbKey(resolutionPart);
+      if (file && resKey) return `${file}|${resKey}`;
+      if (resKey) return resKey;
+    }
+
+    // Cause key fallback
+    if (causePart) {
+      const causeKey = refineBreadcrumbKey(causePart);
+      if (file && causeKey) return `${file}|${causeKey}`;
+      if (causeKey) return causeKey;
+    }
+
+    // Final fallback for → lines: just the file
+    if (file) return file;
+  }
+
+  // V1 fallback: "edited auth.ts" → "auth.ts"
+  const fileMatch1 = text.match(/(?:edited |read |wrote |created |deleted )?(\S+\.\w{1,12})/);
+  if (fileMatch1) return fileMatch1[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);

package/__tests__/helpers.ts

@@ -1,135 +0,0 @@
-/**
- * Helpers for constructing mock session entries and messages.
- *
- * These mirror pi-agent-core types but use loose object shapes
- * so we don't need the actual runtime dependency in tests.
- */
-
-export interface MockEntry {
-  type: string;
-  id?: string;
-  message?: {
-    role?: string;
-    content?: unknown;
-    stopReason?: string;
-  };
-  firstKeptEntryId?: string;
-  summary?: string;
-  timestamp?: string;
-}
-
-let nextId = 1;
-
-function makeId(): string {
-  return `entry_${nextId++}`;
-}
-
-export function resetIds(): void {
-  nextId = 1;
-}
-
-export function makeUserEntry(
-  text: string,
-  overrides?: Partial<MockEntry>,
-): MockEntry {
-  const id = makeId();
-  return {
-    type: "message",
-    id,
-    message: {
-      role: "user",
-      content: [{ type: "text", text }],
-    },
-    ...overrides,
-  };
-}
-
-export function makeAssistantEntry(
-  text: string,
-  stopReason = "stop",
-  overrides?: Partial<MockEntry>,
-): MockEntry {
-  const id = makeId();
-  return {
-    type: "message",
-    id,
-    message: {
-      role: "assistant",
-      content: [{ type: "text", text }],
-      stopReason,
-    },
-    ...overrides,
-  };
-}
-
-export function makeToolResultEntry(
-  toolCallId: string,
-  content: string,
-  overrides?: Partial<MockEntry>,
-): MockEntry {
-  const id = makeId();
-  return {
-    type: "message",
-    id,
-    message: {
-      role: "toolResult",
-      content: [{ type: "toolResult", toolCallId, content }],
-    },
-    ...overrides,
-  };
-}
-
-export function makeCompactionEntry(
-  firstKeptEntryId: string,
-  overrides?: Partial<MockEntry>,
-): MockEntry {
-  const id = makeId();
-  return {
-    type: "compaction",
-    id,
-    firstKeptEntryId,
-    summary: "Compaction summary",
-    ...overrides,
-  };
-}
-
-/**
- * Build a context snapshot dict matching Agent.state.messages shape.
- * Used for testing the "continue from assistant message" scenarios.
- */
-export interface ContextMessage {
-  role: string;
-  content: unknown;
-  stopReason?: string;
-}
-
-export function makeContextMessages(
-  ...msgs: ContextMessage[]
-): ContextMessage[] {
-  return msgs;
-}
-
-export function userMsg(text: string): ContextMessage {
-  return { role: "user", content: [{ type: "text", text }] };
-}
-
-export function assistantMsg(
-  text: string,
-  stopReason = "stop",
-): ContextMessage {
-  return { role: "assistant", content: [{ type: "text", text }], stopReason };
-}
-
-export function toolResultMsg(
-  toolCallId: string,
-  content: string,
-): ContextMessage {
-  return {
-    role: "toolResult",
-    content: [{ type: "toolResult", toolCallId, content }],
-  };
-}
-
-export function compactionSummaryMsg(summary: string): ContextMessage {
-  return { role: "user", content: [{ type: "compactionSummary", text: summary }] };
-}