omp-vcc 0.1.2 → 0.1.5

package/extensions/vcc-core/hook.ts

@@ -52,6 +52,26 @@ export interface CompactionStats {
   smartFromKeep?: number;
   reason?: CompactionReason;
   willRetry?: boolean;
+  /** Tokens before compaction (from preparation). */
+  tokensBefore?: number;
+  /** Summary char length */
+  summaryChars?: number;
+  /** Summary tokens estimate via calibrated cpt */
+  summaryTokensEst?: number;
+  /** Estimated tokens after = summaryTokensEst + keptTokensEst */
+  tokensAfterEst?: number;
+  /** Authoritative tokensAfter from host (compactionEntry) */
+  tokensAfter?: number;
+  /** Estimated saved = tokensBefore - tokensAfterEst */
+  tokensSavedEst?: number;
+  /** Authoritative saved */
+  tokensSaved?: number;
+  /** Estimated percent 0-100 */
+  savedPercentEst?: number;
+  /** Authoritative percent */
+  savedPercent?: number;
+  /** When compaction occurred */
+  timestamp?: number;
 }
 
 export type BudgetCutKind = "no_anchor" | "oversized_tail";
@@ -61,17 +81,39 @@ let lastStats: CompactionStats | null = null;
 let lastCompactWasPiVcc = false;
 let pendingFollowUpPrompt: string | null = null;
 let pendingAutoContinueTimer: any = null;
+let globalHistory: CompactionStats[] = [];
 // Per-pi state to avoid cross-session pollution when multiple sessions share the
 // same ESM module singleton (e.g. main + subagents). Module globals remain as
 // fallback for host-free tests that call getLastCompactionStats() without a pi.
-const perPi = new WeakMap<any, { lastStats: CompactionStats | null; lastCompactWasPiVcc: boolean; pendingFollowUpPrompt: string | null; pendingAutoContinueTimer: any }>();
+const perPi = new WeakMap<any, { lastStats: CompactionStats | null; lastCompactWasPiVcc: boolean; pendingFollowUpPrompt: string | null; pendingAutoContinueTimer: any; statsHistory: CompactionStats[] }>();
+// Track strong refs for test helper clearCompactionHistoryForTests: WeakMap keys
+// cannot be enumerated, so keep a Set for test-only cleanup.
+const perPiKeys = new Set<any>();
+// Guard eager chainShakeHint to avoid recursion: tracks pis currently chaining.
+const pendingChainShake = new WeakSet<object>();
 const getPerPi = (pi: any) => {
   if (!pi || typeof pi !== "object") return null;
   let s = perPi.get(pi);
-  if (!s) { s = { lastStats: null, lastCompactWasPiVcc: false, pendingFollowUpPrompt: null, pendingAutoContinueTimer: null }; perPi.set(pi, s); }
+  if (!s) { s = { lastStats: null, lastCompactWasPiVcc: false, pendingFollowUpPrompt: null, pendingAutoContinueTimer: null, statsHistory: [] }; perPi.set(pi, s); perPiKeys.add(pi); }
+  if (!s.statsHistory) s.statsHistory = [];
   return s;
 };
-const setLastStats = (pi: any, v: CompactionStats | null) => { lastStats = v; const s = getPerPi(pi); if (s) s.lastStats = v; };
+const setLastStats = (pi: any, v: CompactionStats | null) => {
+  if (v && v.timestamp == null) v.timestamp = Date.now();
+  lastStats = v;
+  const s = getPerPi(pi);
+  if (s) {
+    s.lastStats = v;
+    if (v) {
+      s.statsHistory.push(v);
+      if (s.statsHistory.length > 50) s.statsHistory.shift();
+    }
+  }
+  if (v) {
+    globalHistory.push(v);
+    if (globalHistory.length > 50) globalHistory.shift();
+  }
+};
 const setLastCompactWasPiVcc = (pi: any, v: boolean) => { lastCompactWasPiVcc = v; const s = getPerPi(pi); if (s) s.lastCompactWasPiVcc = v; };
 const setPendingFollowUpPrompt = (pi: any, v: string | null) => { pendingFollowUpPrompt = v; const s = getPerPi(pi); if (s) s.pendingFollowUpPrompt = v; };
 const getPendingFollowUpPrompt = (pi: any) => { const s = getPerPi(pi); return s ? s.pendingFollowUpPrompt : pendingFollowUpPrompt; };
@@ -135,25 +177,131 @@ const scheduleAutoContinue = (pi: any) => {
   }, 0);
 };
 
-export const getLastCompactionStats = () => lastStats;
-
+export const getLastCompactionStats = (pi?: any) => {
+  if (pi) {
+    const s = getPerPi(pi);
+    return s?.lastStats ?? null;
+  }
+  return lastStats;
+};
 const formatTokens = (n: number): string => {
   if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
   return String(n);
 };
 
 export const formatCompactionStats = (stats: CompactionStats): string => {
+  const before = stats.tokensBefore ?? 0;
+  const after = stats.tokensAfter ?? stats.tokensAfterEst ?? 0;
+  const savedRaw = stats.tokensSaved ?? stats.tokensSavedEst;
+  const saved = typeof savedRaw === "number" ? savedRaw : (before > 0 && after > 0 ? Math.max(0, before - after) : 0);
+  const percentRaw = stats.savedPercent ?? stats.savedPercentEst;
+  const percent = typeof percentRaw === "number" ? percentRaw : (before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0);
+  const hasSavings = before > 0 && after > 0 && before > after && saved > 0 && percent > 0;
+  const savingsPrefix = hasSavings ? `${formatTokens(before)}→${formatTokens(after)} (${percent}% saved, ~${formatTokens(saved)}) · ` : "";
+  const keptTokens = stats.keptTokensEst ?? 0;
+  const summarized = stats.summarized ?? 0;
+  const keptTurns = stats.keptUserTurns ?? 0;
+  const totalTurns = stats.totalUserTurns ?? 0;
   if (stats.budgetCut) {
     const reason = stats.budgetCut === "no_anchor" ? "no user anchor" : "oversized tail";
-    return `omp-vcc: kept ~${formatTokens(stats.keptTokensEst)} tok tail (mid-turn cut, ${reason}), summarized ${stats.summarized}.`;
+    if (savingsPrefix) {
+      return `omp-vcc: ${savingsPrefix}kept ~${formatTokens(keptTokens)} tok tail (mid-turn cut, ${reason}), summarized ${summarized}.`;
+    }
+    return `omp-vcc: kept ~${formatTokens(keptTokens)} tok tail (mid-turn cut, ${reason}), summarized ${summarized}.`;
   }
-  const notes: string[] = [`summarized ${stats.summarized}`];
+  const notes: string[] = [`summarized ${summarized}`];
   if (stats.smartKeepAdjusted) {
     notes.push("smart-keep");
   }
-  return `omp-vcc: kept ${stats.keptUserTurns}/${stats.totalUserTurns} turns, ~${formatTokens(stats.keptTokensEst)} tok (${notes.join(", ")}).`;
+  if (savingsPrefix) {
+    return `omp-vcc: ${savingsPrefix}kept ${keptTurns}/${totalTurns} turns, ~${formatTokens(keptTokens)} tok (${notes.join(", ")}).`;
+  }
+  return `omp-vcc: kept ${keptTurns}/${totalTurns} turns, ~${formatTokens(keptTokens)} tok (${notes.join(", ")}).`;
+};
+
+export const getCompactionHistory = (pi?: any): CompactionStats[] => {
+  if (pi) {
+    const s = getPerPi(pi);
+    if (s?.statsHistory) return [...s.statsHistory];
+  }
+  return [...globalHistory];
+};
+
+export const clearCompactionHistoryForTests = () => {
+  globalHistory = [];
+  lastStats = null;
+  lastCompactWasPiVcc = false;
+  pendingFollowUpPrompt = null;
+  clearTimeout(pendingAutoContinueTimer as any);
+  pendingAutoContinueTimer = null;
+  for (const pi of perPiKeys) {
+    const s = perPi.get(pi);
+    if (s) {
+      s.statsHistory = [];
+      s.lastStats = null;
+      s.lastCompactWasPiVcc = false;
+      s.pendingFollowUpPrompt = null;
+      clearTimeout(s.pendingAutoContinueTimer as any);
+      s.pendingAutoContinueTimer = null;
+    }
+    // Remove strong ref so pi can be GC'd and WeakMap entry cleared; fresh
+    // getPerPi(pi) will recreate if this pi is reused, but tests create fresh
+    // pi objects each time, so clearing prevents unbounded Set growth across
+    // the 377-test suite.
+    perPi.delete(pi);
+  }
+  perPiKeys.clear();
+};
+
+export const formatStatsTable = (history: CompactionStats[]): string => {
+  if (!history || history.length === 0) return "No compactions yet.";
+  const header = "| # | Before → After | Saved | Kept | Summarized | When |";
+  const sep = "|---|---|---|---|---|---|---|";
+  const rows = history.map((s, idx) => {
+    const before = s.tokensBefore ?? 0;
+    const after = s.tokensAfter ?? s.tokensAfterEst ?? 0;
+    const saved = s.tokensSaved ?? s.tokensSavedEst ?? (before > 0 && after > 0 ? Math.max(0, before - after) : 0);
+    const percent = s.savedPercent ?? s.savedPercentEst ?? (before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0);
+    const beforeAfter = before > 0 && after > 0 ? `${formatTokens(before)}→${formatTokens(after)}` : `${formatTokens(before)}→${formatTokens(after)}`;
+    const savedStr = saved > 0 ? `${formatTokens(saved)} (${percent}%)` : "—";
+    const keptTurns = s.keptUserTurns ?? 0;
+    const totalTurns = s.totalUserTurns ?? 0;
+    const keptTok = s.keptTokensEst ?? 0;
+    const summarized = s.summarized ?? 0;
+    const keptStr = `${keptTurns}/${totalTurns} turns, ~${formatTokens(keptTok)} tok${s.budgetCut ? ` (${s.budgetCut})` : ""}`;
+    const when = s.timestamp ? new Date(s.timestamp).toISOString().slice(0, 19).replace("T", " ") : "—";
+    return `| ${idx + 1} | ${beforeAfter} | ${savedStr} | ${keptStr} | ${summarized} | ${when} |`;
+  });
+  return [header, sep, ...rows].join("\n");
+};
+
+export const formatLastStatsDetail = (stats: CompactionStats | null): string => {
+  if (!stats) return "No compaction has run yet.";
+  const before = stats.tokensBefore ?? 0;
+  const after = stats.tokensAfter ?? stats.tokensAfterEst ?? 0;
+  const saved = stats.tokensSaved ?? stats.tokensSavedEst ?? (before > 0 && after > 0 ? Math.max(0, before - after) : 0);
+  const percent = stats.savedPercent ?? stats.savedPercentEst ?? (before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0);
+  const kept = stats.kept ?? 0;
+  const keptTurns = stats.keptUserTurns ?? 0;
+  const totalTurns = stats.totalUserTurns ?? 0;
+  const keptTok = stats.keptTokensEst ?? 0;
+  const summaryTok = stats.summaryTokensEst ?? 0;
+  const summaryChars = stats.summaryChars ?? 0;
+  const summarized = stats.summarized ?? 0;
+  const lines = [
+    `**Last compaction** ${stats.timestamp ? new Date(stats.timestamp).toISOString() : ""}`,
+    `- Before → After: **${formatTokens(before)} → ${formatTokens(after)}** (${percent}% saved, ~${formatTokens(saved)})`,
+    `- Summary: ~${formatTokens(summaryTok)} tok (${summaryChars} chars), kept tail ~${formatTokens(keptTok)} tok (${kept} msgs, ${keptTurns}/${totalTurns} turns)`,
+    `- Summarized: ${summarized} messages${stats.smartKeepAdjusted ? ` (smart-keep ${stats.smartFromKeep}→${keptTurns})` : ""}${stats.budgetCut ? ` · budgetCut:${stats.budgetCut}` : ""}`,
+    `- Details: ${stats.reason ? `reason=${stats.reason}` : "reason=auto"}${stats.willRetry ? " willRetry=true" : ""}`,
+  ];
+  if (stats.tokensAfter != null && stats.tokensAfterEst != null && stats.tokensAfter !== stats.tokensAfterEst) {
+    lines.push(`- Note: est after ${formatTokens(stats.tokensAfterEst)} vs authoritative ${formatTokens(stats.tokensAfter)}`);
+  }
+  return lines.join("\n");
 };
 
+
 const readCompactionEventContext = (event: unknown): { reason?: CompactionReason; willRetry: boolean } => {
   const raw = event as { reason?: unknown; willRetry?: unknown };
   const reason = raw.reason === "manual" || raw.reason === "threshold" || raw.reason === "overflow"
@@ -584,6 +732,17 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     // Otherwise, only handle when user opted in via settings.
     const { isPiVcc, keepUserTurns, keepUserTurnsExplicit, followUpPrompt } = parseCompactionInstructions(customInstructions);
     setPendingFollowUpPrompt(pi, null);
+    // Explicit host mode bypass: when the host signals an explicit compact mode
+    // (e.g. /compact snapcompact or --mode shake), let the host walker handle it
+    // even though overrideDefaultCompaction is true. This enables sequential
+    // VCC → snapcompact/shake combinations. The event field is only present when
+    // the optional native vcc patch is applied or a future host exposes it; when
+    // absent this branch is no-op and the existing override semantics remain.
+    const explicitMode = (event as any).compactMode ?? (event as any).explicitMode ?? (event as any).mode;
+    if (!isPiVcc && typeof explicitMode === "string" && explicitMode) {
+      const m = explicitMode.toLowerCase();
+      if (m === "snapcompact" || m === "shake" || m === "soft" || m === "remote" || m === "handoff") return;
+    }
     if (!isPiVcc && !settings.overrideDefaultCompaction) return;
 
     const calibrationCut = buildOwnCut(branchEntries as any[], 0);
@@ -726,21 +885,7 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       (sum: number, e: any) => sum + estimateMessageContentChars(e.message?.content),
       0,
     );
-    setLastStats(pi, {
-      summarized: agentMessages.length,
-      kept: keptEntries.length,
-      keptUserTurns: ownCut.keptUserTurns,
-      totalUserTurns: ownCut.totalUserTurns,
-      requestedKeepUserTurns: ownCut.requestedKeepUserTurns,
-      keepUserTurnsExplicit,
-      keepFallbackToCompactAll: ownCut.keepFallbackToCompactAll,
-      keptTokensEst: estimateTokensFromChars(keptChars, tokenEstimate.charsPerToken),
-      smartKeepAdjusted: smartKeep.smartAdjusted,
-      smartFromKeep: smartKeep.fromKeep,
-      budgetCut: ownCut.ok ? ownCut.budgetCut : undefined,
-      reason,
-      willRetry,
-    });
+    const keptTokensEst = estimateTokensFromChars(keptChars, tokenEstimate.charsPerToken);
     const config = settings;
 
     // Ranked compaction: keep the highest-signal blocks under a token budget
@@ -776,6 +921,35 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       },
     });
 
+    const tokensBefore = typeof preparation.tokensBefore === "number" ? preparation.tokensBefore : 0;
+    const summaryChars = summary.length;
+    const summaryTokensEst = estimateTokensFromChars(summaryChars, tokenEstimate.charsPerToken);
+    const tokensAfterEst = summaryTokensEst + keptTokensEst;
+    const tokensSavedEst = tokensBefore > 0 ? Math.max(0, tokensBefore - tokensAfterEst) : 0;
+    const savedPercentEst = tokensBefore > 0 && tokensSavedEst > 0 ? Math.round((tokensSavedEst / tokensBefore) * 100) : 0;
+
+    setLastStats(pi, {
+      summarized: agentMessages.length,
+      kept: keptEntries.length,
+      keptUserTurns: ownCut.keptUserTurns,
+      totalUserTurns: ownCut.totalUserTurns,
+      requestedKeepUserTurns: ownCut.requestedKeepUserTurns,
+      keepUserTurnsExplicit,
+      keepFallbackToCompactAll: ownCut.keepFallbackToCompactAll,
+      keptTokensEst,
+      smartKeepAdjusted: smartKeep.smartAdjusted,
+      smartFromKeep: smartKeep.fromKeep,
+      budgetCut: ownCut.ok ? ownCut.budgetCut : undefined,
+      reason,
+      willRetry,
+      tokensBefore,
+      summaryChars,
+      summaryTokensEst,
+      tokensAfterEst,
+      tokensSavedEst,
+      savedPercentEst,
+    });
+
     const branchIds = branchEntries.map((e: any) => e.id);
     const cutIdx = branchIds.indexOf(firstKeptEntryId);
     const cutWindow = cutIdx >= 0
@@ -787,6 +961,9 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
         }))
       : [];
 
+    const KNOWN_SECTIONS = new Set(["Session Goal", "Files And Changes", "Commits", "Outstanding Context", "User Preferences"]);
+    const extractKnownSections = (text: string) =>
+      [...text.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]).filter((h) => KNOWN_SECTIONS.has(h));
     dbg(config, {
       usedOwnCut: true,
       budgetCut: ownCut.budgetCut,
@@ -797,21 +974,39 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       convertedMessages: messages.length,
       firstKeptEntryId,
       cutWindow,
-      tokensBefore: preparation.tokensBefore,
+      tokensBefore,
       tokenEstimate,
       summaryLength: summary.length,
       summaryPreview: summary.slice(0, 500),
-      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+      sections: extractKnownSections(summary),
+      savings: {
+        tokensBefore,
+        summaryChars,
+        summaryTokensEst,
+        keptTokensEst,
+        tokensAfterEst,
+        tokensSavedEst,
+        savedPercentEst,
+      },
     });
 
     const details: PiVccCompactionDetails = {
       compactor: "omp-vcc",
-      version: 1,
-      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+      version: 2,
+      sections: extractKnownSections(summary),
       sourceMessageCount: agentMessages.length,
       previousSummaryUsed: Boolean(preparation.previousSummary),
       reason,
       willRetry,
+      savings: {
+        tokensBefore,
+        summaryChars,
+        summaryTokensEst,
+        keptTokensEst,
+        tokensAfterEst,
+        tokensSavedEst,
+        savedPercentEst,
+      },
     };
 
     setLastCompactWasPiVcc(pi, isPiVcc);
@@ -831,11 +1026,44 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     const followUpPrompt = getPendingFollowUpPrompt(pi);
     setPendingFollowUpPrompt(pi, null);
     const per = getPerPi(pi);
+    const stats = per ? per.lastStats : lastStats;
+    if (!stats) return;
+    // Enrich with authoritative tokensAfter from host if available (even for pi-vcc manual, before early return)
+    const entry: any = (event as any).compactionEntry;
+    if (entry && typeof entry.tokensAfter === "number" && typeof entry.tokensBefore === "number") {
+      const before = entry.tokensBefore;
+      const after = entry.tokensAfter;
+      const saved = Math.max(0, before - after);
+      const percent = before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0;
+      if (per && per.lastStats) {
+        per.lastStats.tokensAfter = after;
+        per.lastStats.tokensSaved = saved;
+        per.lastStats.savedPercent = percent;
+        per.lastStats.tokensBefore = before;
+      }
+      if (lastStats) {
+        lastStats.tokensAfter = after;
+        lastStats.tokensSaved = saved;
+        lastStats.savedPercent = percent;
+        lastStats.tokensBefore = before;
+      }
+      (stats as any).tokensAfter = after;
+      (stats as any).tokensSaved = saved;
+      (stats as any).savedPercent = percent;
+      (stats as any).tokensBefore = before;
+      try {
+        const cfg = loadSettings(ctx);
+        if (cfg.debug) {
+          dbg(cfg, {
+            authoritativeSavings: { tokensBefore: before, tokensAfter: after, tokensSaved: saved, savedPercent: percent },
+            eventEntry: { id: entry.id, tokensBefore: entry.tokensBefore, tokensAfter: entry.tokensAfter },
+          });
+        }
+      } catch {}
+    }
     const isPiVccLast = per ? per.lastCompactWasPiVcc : lastCompactWasPiVcc;
     if (isPiVccLast) return; // /pi-vcc handles its own toast via onComplete
     if (willRetry) return;
-    const stats = per ? per.lastStats : lastStats;
-    if (!stats) return;
     // omp's SessionCompactEvent is {compactionEntry, fromExtension} only
     // (shared-events.ts:84-89); reason/willRetry are always undefined/false
     // under real omp runs. Treat undefined as auto (threshold/overflow) when
@@ -843,6 +1071,25 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     const isLargeCompaction = (stats.summarized > 10) || (stats.kept > 5) || (stats.keptTokensEst > 2000);
     const shouldContinueAfterAutoCompact = (reason === "threshold" || reason === "overflow" || (reason == null && isLargeCompaction)) && loadSettings(ctx).continueAfterThresholdCompact;
     scheduleCompactionStatsNotify(ctx, stats);
+    // Eager post-VCC shake chain (chainShakeHint). Host rescue already handles
+    // dead-end; this forces a second shake entry even when headroom was made.
+    try {
+      const cfgChain = loadSettings(ctx);
+      const ctxMaybe = ctx as unknown as Record<string, unknown>;
+      const compactFn = ctxMaybe["compact"];
+      if (cfgChain.chainShakeHint && typeof compactFn === "function" && !pendingChainShake.has(pi as unknown as object) && !willRetry && !isPiVccLast) {
+        pendingChainShake.add(pi as unknown as object);
+        const maybePromise = (compactFn as unknown as (o: unknown) => Promise<void>).call(ctx, { mode: "shake" } as unknown);
+        const asPromise = maybePromise as unknown as Promise<void> | void;
+        if (asPromise && typeof (asPromise as unknown as Promise<void>).catch === "function") {
+          (asPromise as unknown as Promise<void>).catch(() => {}).finally(() => {
+            setTimeout(() => { try { pendingChainShake.delete(pi as unknown as object); } catch {} }, 2000);
+          });
+        } else {
+          setTimeout(() => { try { pendingChainShake.delete(pi as unknown as object); } catch {} }, 2000);
+        }
+      }
+    } catch {}
     if (followUpPrompt) {
       try {
         await pi.sendUserMessage(followUpPrompt);
@@ -992,7 +1239,7 @@ export const registerPiVccCommand = (pi: any) => {
       ctx.compact({
         customInstructions: buildPiVccCustomInstructions(keepUserTurns),
         onComplete: () => {
-          const stats = getLastCompactionStats();
+          const stats = getLastCompactionStats(pi);
           if (stats) {
             scheduleCompactionStatsNotify(ctx, stats);
           } else {
@@ -1014,4 +1261,63 @@ export const registerPiVccCommand = (pi: any) => {
       });
     },
   });
+};
+export const registerVccStatsTool = (pi: any) => {
+  const hasBoolean = typeof pi?.zod?.boolean === "function";
+  const schema = pi?.zod?.object && hasBoolean
+    ? pi.zod.object({
+        history: pi.zod.boolean().optional().describe("Include full history table of all compactions in this session"),
+      })
+    : {};
+  pi.registerTool({
+    name: "vcc_stats",
+    label: "VCC Stats",
+    description: "Show omp-vcc compaction savings — last compaction before→after, tokens saved, percent, and optional history of all compactions in this session. Divider in transcript already shows 256K→20K; this tool surfaces the same numbers with kept/summarized details.",
+    approval: "read",
+    parameters: schema,
+    async execute(_toolCallId: string, params: any, _signal: unknown, _onUpdate: unknown, _ctx: any) {
+      const history = getCompactionHistory(pi);
+      const last = getLastCompactionStats(pi);
+      const wantHistory = params?.history === true;
+      if (!last && history.length === 0) {
+        return { content: [{ type: "text", text: "No compactions yet in this session." }], details: undefined };
+      }
+      if (wantHistory) {
+        const table = formatStatsTable(history);
+        const detail = last ? `\n\n${formatLastStatsDetail(last)}` : "";
+        return { content: [{ type: "text", text: `${table}${detail}` }], details: undefined };
+      }
+      const detail = formatLastStatsDetail(last);
+      const table = history.length > 1 ? `\n\nHistory:\n${formatStatsTable(history)}` : "";
+      return { content: [{ type: "text", text: `${detail}${table}` }], details: undefined };
+    },
+  } as unknown as Parameters<(typeof pi)["registerTool"]>[0]);
+};
+
+export const registerVccStatsCommand = (pi: any) => {
+  const handler = async (args: string, ctx: any) => {
+    const raw = (args || "").trim().toLowerCase();
+    const wantHistory = raw.includes("history") || raw.includes("--history") || raw.includes("all");
+    const history = getCompactionHistory(pi);
+    const last = getLastCompactionStats(pi);
+    const piAny = pi as unknown as { sendMessage?: (msg: unknown, opts?: unknown) => void };
+    if (!last && history.length === 0) {
+      try { piAny.sendMessage?.({ customType: "vcc-stats", content: "No compactions yet in this session.", display: true }, { triggerTurn: false }); } catch {}
+      try { ctx?.ui?.notify?.("No compactions yet.", "info"); } catch {}
+      return;
+    }
+    let output: string;
+    if (wantHistory) {
+      const table = formatStatsTable(history);
+      const detail = last ? `\n\n${formatLastStatsDetail(last)}` : "";
+      output = `${table}${detail}`;
+    } else {
+      const detail = formatLastStatsDetail(last);
+      const table = history.length > 1 ? `\n\nHistory (${history.length} compactions):\n${formatStatsTable(history)}` : "";
+      output = `${detail}${table}`;
+    }
+    try { piAny.sendMessage?.({ customType: "vcc-stats", content: output, display: true }, { triggerTurn: false }); } catch {}
+    try { ctx?.ui?.notify?.(`vcc_stats: ${history.length} compaction(s)`, "info"); } catch {}
+  };
+  pi.registerCommand("vcc-stats", { description: "Show omp-vcc compaction savings (last + history)", handler });
 };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "omp-vcc",
-  "version": "0.1.2",
+  "version": "0.1.5",
+  "type": "module",
   "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
   "author": "Zhu Lin <zhulin@czl.my>",
   "repository": {
@@ -25,7 +26,6 @@
   "files": [
     "extensions",
     "skills",
-    "commands",
     "scripts",
     "types.d.ts"
   ],
@@ -34,10 +34,6 @@
     "extensions": [
       "./extensions/main.ts"
     ],
-    "commands": [
-      "./commands/omp-vcc.md",
-      "./commands/vcc-recall.md"
-    ],
     "settings": {
       "vccEnabled": {
         "type": "boolean",
@@ -63,6 +59,11 @@
         "type": "boolean",
         "default": false,
         "description": "Write debug snapshot to /tmp/omp-vcc-debug.json"
+      },
+      "chainShakeHint": {
+        "type": "boolean",
+        "default": false,
+        "description": "Eager post-VCC shake chain (host rescue is automatic; this forces a second shake even when VCC created headroom)"
       }
     }
   },
@@ -71,10 +72,6 @@
     "extensions": [
       "./extensions/main.ts"
     ],
-    "commands": [
-      "./commands/omp-vcc.md",
-      "./commands/vcc-recall.md"
-    ],
     "settings": {
       "vccEnabled": {
         "type": "boolean",
@@ -100,6 +97,11 @@
         "type": "boolean",
         "default": false,
         "description": "Write debug snapshot to /tmp/omp-vcc-debug.json"
+      },
+      "chainShakeHint": {
+        "type": "boolean",
+        "default": false,
+        "description": "Eager post-VCC shake chain (host rescue is automatic; this forces a second shake even when VCC created headroom)"
       }
     }
   },
@@ -107,6 +109,8 @@
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
     "smoke": "bun run scripts/smoke.ts",
+    "e2e": "bun run scripts/e2e.ts",
+    "e2e:direct": "bun test tests/e2e --timeout 120000",
     "postuninstall": "node scripts/uninstall-reset.js || true",
     "prepublishOnly": "npm run typecheck && npm test && npm run smoke"
   }

package/scripts/e2e.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+// @ts-nocheck
+// Usage: bun run e2e   or   bun run scripts/e2e.ts [--timeout 120000]
+
+import { mkdtempSync, existsSync, mkdirSync, cpSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const timeoutArg = process.argv.find((a) => a.startsWith("--timeout"));
+const timeout = timeoutArg ? Number(timeoutArg.split("=")[1] ?? 120000) : 120000;
+const verbose = process.argv.includes("--verbose");
+
+console.log("== omp-vcc E2E runner ==");
+
+const ompDir = mkdtempSync(join(tmpdir(), "omp-vcc-e2e-runner-"));
+const configPath = join(ompDir, "config.json");
+console.log(`OMP_DIR=${ompDir}`);
+console.log(`OMP_VCC_CONFIG_PATH=${configPath}`);
+
+let failures = 0;
+
+async function probeOmp(): Promise<void> {
+  try {
+    const proc = Bun.spawn(["omp", "--help"], { stdout: "pipe", stderr: "pipe" });
+    await proc.exited;
+    const out = await new Response(proc.stdout).text().catch(() => "");
+    const err = await new Response(proc.stderr).text().catch(() => "");
+    const help = out + err;
+    if (verbose) console.log(help.slice(0, 2000));
+    const hasPrint = /--print\b/.test(help);
+    const hasExtension = /--extension\b|-e\b/.test(help);
+    const hasPlugin = /\bplugin\b/.test(help);
+    console.log(`probe omp --help: hasPrint=${hasPrint} hasExtension=${hasExtension} hasPlugin=${hasPlugin}`);
+    if (!hasPlugin) console.log("note: omp plugin subcommand not found — isolated plugin link test will be skipped");
+  } catch (e) {
+    console.log(`probe failed (omp not on PATH?): ${e}`);
+  }
+}
+
+await probeOmp();
+
+// Try plugin link in isolated dir (best effort, skip if omp missing)
+try {
+  const linkProc = Bun.spawn(["omp", "plugin", "link", process.cwd()], {
+    env: { ...process.env, OMP_DIR: ompDir, PI_CODING_AGENT_DIR: ompDir, OMP_VCC_CONFIG_PATH: configPath, PI_VCC_CONFIG_PATH: configPath },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  await linkProc.exited;
+  const code = linkProc.exitCode ?? 0;
+  if (code === 0) {
+    console.log("omp plugin link ok (isolated)");
+    const doctor = Bun.spawn(["omp", "plugin", "doctor"], {
+      env: { ...process.env, OMP_DIR: ompDir, PI_CODING_AGENT_DIR: ompDir, OMP_VCC_CONFIG_PATH: configPath },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await doctor.exited;
+    const out = await new Response(doctor.stdout).text().catch(() => "");
+    console.log(out.slice(0, 1500));
+  } else {
+    const err = await new Response(linkProc.stderr).text().catch(() => "");
+    console.log(`omp plugin link skipped or failed (code ${code}): ${err.slice(0, 500)}`);
+  }
+} catch (e) {
+  console.log(`omp plugin link probe skipped: ${e}`);
+}
+
+console.log(`\n== running bun test tests/e2e --timeout ${timeout} ==`);
+const env = {
+  ...process.env,
+  OMP_DIR: ompDir,
+  PI_CODING_AGENT_DIR: ompDir,
+  OMP_VCC_CONFIG_PATH: configPath,
+  PI_VCC_CONFIG_PATH: configPath,
+};
+const testProc = Bun.spawn(["bun", "test", "tests/e2e", "--timeout", String(timeout)], {
+  env,
+  stdout: "pipe",
+  stderr: "pipe",
+});
+const stdoutChunks: string[] = [];
+const stderrChunks: string[] = [];
+// Stream
+const outReader = testProc.stdout.getReader();
+const errReader = testProc.stderr.getReader();
+async function drain(reader: ReadableStreamDefaultReader<Uint8Array>, store: string[], isErr: boolean) {
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const text = new TextDecoder().decode(value);
+      store.push(text);
+      if (isErr) process.stderr.write(text);
+      else process.stdout.write(text);
+    }
+  } catch {}
+}
+await Promise.all([drain(outReader as any, stdoutChunks, false), drain(errReader as any, stderrChunks, true)]);
+const exitCode = await testProc.exited;
+
+console.log(`\n== bun test exit code: ${exitCode} ==`);
+
+// collect debug artifacts
+const artifactsDir = join(process.cwd(), "artifacts", "e2e-debug");
+try {
+  mkdirSync(artifactsDir, { recursive: true });
+  for (const p of ["/tmp/omp-vcc-debug.json", "/tmp/pi-vcc-debug.json"]) {
+    if (existsSync(p)) {
+      const dest = join(artifactsDir, p.split("/").pop()!);
+      cpSync(p, dest);
+      console.log(`artifact collected: ${p} -> ${dest}`);
+    }
+  }
+  if (existsSync(configPath)) {
+    cpSync(configPath, join(artifactsDir, "isolated-config.json"));
+  }
+} catch (e) {
+  console.log(`artifact collection warning: ${e}`);
+}
+
+// cleanup isolated dir (keep artifacts)
+try { rmSync(ompDir, { recursive: true, force: true }); } catch {}
+console.log(`isolated OMP_DIR removed: ${ompDir}`);
+
+if (exitCode !== 0) {
+  console.log("\nE2E FAILED");
+  process.exit(exitCode ?? 1);
+} else {
+  console.log("\nAll E2E checks passed.");
+}